PC-Blue - MS DOS Public Domain Library

home *** CD-ROM | disk | FTP | other *** search

/ PC-Blue - MS DOS Public Domain Library / PC-Blue MS-DOS Public Domain Library - NYACC.iso / vol434 / xwindow.arc / MANUAL.DOC

Wrap

Text File | 1987-12-18 | 761.0 KB | 27,239 lines

Xlib - C Language X Interface Protocol Version 11 Jim Gettys Digital Equipment Corporation Systems Research Center MIT Project Athena Ron Newman Massachusetts Institute of Technology MIT Project Athena Robert W. Scheifler Massachusetts Institute of Technology Laboratory for Computer Science December 18, 1987 - 2 - The X Window System is a trademark of MIT. ULTRIX, ULTRIX-32, ULTRIX-32m, ULTRIX-32w, and VAX/VMS are trademarks of Digital Equipment Corporation. UNIX is a trademark of AT&T Bell Laboratories. Copyright c 1985, 1986, 1987, Massachusetts Institute of Technology, Cambridge, Massachusetts, and Digital Equipment Corporation, Maynard, Massachusetts. Permission to use, copy, modify and distribute this documen- tation for any purpose and without fee is hereby granted, provided that the above copyright notice appears in all copies and that both that copyright notice and this permis- sion notice appear in supporting documentation, and that the name of M.I.T. or Digital not be used in in advertising or publicity pertaining to distribution of the software without specific, written prior permission. M.I.T and Digital makes no representations about the suitability of the software described herein for any purpose. It is provided ``as is'' without express or implied warranty. December 18, 1987 - 3 - Table of Contents Preface Preface Whereas the design and implementation of the first 10 ver- sions of X were primarily the work of three individuals, Robert Scheifler of the MIT Laboratory for Computer Science and Jim Gettys of Digital Equipment Corporation and Ron New- man of MIT, both at MIT Project Athena, X version 11 is the result of the efforts of literally dozens of individuals at almost as many locations and organizations. At the risk of offending some of the players by exclusion, many people deserve special credit and recognition. Our apologies to anyone inadvertently overlooked. First, Phil Karlton and Scott McGregor, both of Digital, for their considerable contributions to the specification of the version 11 protocol. Sue Angebranndt, Raymond Drewry, Todd Newman and Phil Karlton of Digital have worked long and hard to produce the sample server implementation. Todd Brunhoff of Tektronix was ``loaned'' to Project Athena at exactly the right moment to provide very capable and much needed assistance during the alpha and beta releases. He is totally responsible for the successfull integration of sources from multiple sites; we simply wouldn't have a release without him. Ralph Swick of Project Athena and Digital kept it all together for us. He has handled literally thousands of requests for people everywhere and saved the sanity of one of us (JG). His calm good cheer has been a foundation on which we could build. Special thanks must also go to Sam Fuller, Vice President of Corporate Research at Digital, who has remained committed to the widest public availability of X and who made it possible to greatly supplement MIT's resources with the Digital staff in order to make version 11 a reality. Many of the people mentioned here are part of the Western Software Laboratory (Digital UEG-WSL) of the ULTRIX Engineering group, who work for Smokey Wallace, who has been vital to the project's suc- cess; additional others have worked on the toolkit, and are acknowledged there. Our thanks also go to Al Mento and Al Wojtas of Digital's ULTRIX Documentation Group. With good humor and cheer, they took a rough draft of the V11 Xlib manual and made it an infinitely better and more useful document. The work they have done will help many everywhere. We also would like to thank Hal Murray (Digital SRC) and Peter George (Digital VMS) who contributed much by proof reading this manual. December 18, 1987 - 4 - We would like to thank Jeff Dike (Digital UEG), Tom Benson, Jackie Granfield, and Vince Orgovan (Digital VMS) who helped with the library utilities implementation. Hania Gajewska (Digital UEG-WSL) was instrumental in the semantic design of the window manager properties along with Ellis Cohen of CMU and Siemens. Dave Rosenthal of Sun Microsystems also contributed to the protocol and provided the sample generic color frame buffer device dependent code. The alpha and beta test participants deserve recognition as well. It is significant that the bug reports (and many fixes) during alpha and beta test came almost exclusively from just a few of the alpha testers, mostly hardware ven- dors working on product implementations of X. The continued public contribution of vendors and universities is certainly to the benefit of the entire X community. The Version 11 protocol was authored by Bob Scheifler of MIT's Laboratory for computer science. Contributers to the design were: Dave Carver (Digital HPW) Branko Gerovac (Digital HPW) Jim Gettys (MIT/Project Athena, Digital) Phil Karlton (Digital WSL) Scott McGregor (Digital SSG) Ram Rao (Digital UEG) David Rosenthal (Sun) Dave Winchell (Digital UEG) Invited reviewers who provided useful input: Andrew Cherenson (Berkeley) Burns Fisher (Digital) Dan Garfinkel (HP) Leo Hourvitz (Next) Brock Krizan (HP) David Laidlaw (Stellar) Dave Mellinger (Interleaf) Ron Newman (MIT) John Ousterhout (Berkeley) Andrew Palay (ITC CMU) Ralph Swick (MIT/Project Athena, Digital) Craig Taylor (Sun) Jeffery Vroom (Stellar) And of course, we must acknowledge Paul Asente, of Stanford University, who wrote W, the predecessor to X. December 18, 1987 - 5 - And thanks must also go to MIT, Digital Equipment Corpora- tion, and IBM for providing the environment where it could happen. Jim Gettys Systems Research Center MIT / Project Athena Digital Equipment Corporation Ron Newman Project Athena Massachusetts Institute of Technology Robert W. Scheifler Laboratory for Computer Science Massachusetts Institute of Technology September 15, 1987 December 18, 1987 Chapter 1 Introduction to Xlib Introduction to Xlib The X Window System is a network tran- sparent windowing system that was designed at MIT and that runs under 4.3BSD UNIX, ULTRIX-32, many other UNIX variants, VAX/VMS, as well as several other operating systems. X display servers run on computers with either monochrome or color bitmap terminals. The server distributes user input to and accepts output requests from various client programs located either on the same machine or elsewhere in your net- work. Xlib is a C subroutine library that application pro- grams (clients) use to interface with the window system by means of a stream connection. Although a client usually runs on the same machine as the X server it is talking to, this need not be the case. This manual is a descriptive guide to the low-level C language interface to the X Window System protocol. It is neither a tutorial nor a user guide to programming to the X Window System. Other high-level abstractions (for example, those provided by the toolkits for X) are built on top of the Xlib library. For further information about these high-level libraries, see the appropriate toolkit documenta- tion. For general information about the design of X, see ``The X Window System.'' This manual assumes a basic understanding of a graphics win- dow system and of the C programming language. To provide an introduction to X programming, this chapter discusses: o Overview of the X Window System o Naming and argument conventions o Programming considerations 1.1. Overview of the X Window System Some of the terms used in this book are unique to X, while other terms that are common to other window systems have different meanings in X. You may find it helpful to refer to the glossary, located at the end of the book, when you are uncertain of a term's meaning in the context of the X Window System. The X Window System supports one or more screens containing overlapping windows or subwindows. A screen is a physical December 18, 1987 - 2 - monitor and hardware, which may be either color or black and white. There can be multiple screens per display or works- tation. All the windows in an X server are arranged in a strict hierarchy. At the top of the hierarchy are the root win- dows, which cover each of the display screens. Each root window is partially or completely covered by child windows. All windows, except for root windows, have parents. There is usually at least one window per application program. Child windows may in turn have their own children. In this way, an application program can create a tree of arbitrary depth on each screen. A child window may be larger than its parent. That is, part or all of the child window may extend beyond the boundaries of the parent. However, all output to a window is clipped by the boundaries of its parent window. If several children of a window have overlapping locations, one of the children is considered to be on top of or raised over the others, obscuring them. Output to areas covered by other windows will be suppressed by the window system. If a window is obscured by a second window, the window will obscure only those ancestors of the second window, which are also ances- tors of the first window. A window has a border of zero or more pixels in width, which can be any pattern (pixmap) or solid color you like. A win- dow usually but not always has a background pattern which will be repainted by the window system when uncovered. Each window has its own coordinate system. Child windows obscure their parents unless the child windows have no b ackground, and graphic operations in the parent window usually are clipped by the children. Input from X takes the form of events. Events may either be side effects of a command (for example, restacking windows generates exposure events) or completely asynchronous (for example, the keyboard). A client program asks to be informed of events. X never sends events a program did not ask for. X does not take responsibility for the contents of windows. When part or all of a window is hidden and then brought back onto the screen, its contents may be lost, and the client program is notified (by an exposure event) that part or all of the window needs to be repainted. Programs must be prepared to regenerate the contents of windows on demand. X also provides off screen storage of graphics objects, called ``pixmaps.'' Single plane (depth 1) pixmaps are sometimes referred to as ``bitmaps.'' These can be used in most graphics functions interchangably with windows, and are used in various graphics operations to define patterns also December 18, 1987 - 3 - called ``tiles.'' Windows and pixmaps together are referred to as ``drawables.'' Most of the functions in Xlib just add requests to an output buffer. These requests later execute asynchronously on the X server, often referred to as display server. Functions that return values of information stored in the server do not return (that is, they ``block'') until an explicit reply is received or an error occurs. If a nonblocking call results in an error, the error will generally not be reported by a call to an optional error handler until some later, blocking call is made. If it does not want a request to execute asynchronously, a client can follow it with a call to XSync, which will block until all previously buffered asynchronous events have been sent and acted on. As an important side effect, the output buffer is always flushed by a call to any function which returns a value or waits for input (for example, XPending, XNextEvent, XWindowEvent, XFlush, or XSync). Many Xlib functions will return an integer resource ID, which allows you to refer to objects stored on the X server. These can be of type Window, Font, Pixmap, Bitmap, Cursor, and GContext, as defined in the file <X11/X.h>. These resources are created by user requests, and destroyed (or freed) by user requests or when connections closed. Most of these resources are potentially sharable between applica- tions, and in fact, windows are manipulated explicitly by window manager programs. Fonts and cursors are typically shared automatically since the X server treats fonts spe- cially, loading and unloading font storage as needed. GCon- texts should not be shared between applications. Some functions return Status, an integer error indication. If the function fails, it will return a zero (0). If the function returns a status of zero (0), it has not updated the return parameters. Because C does not provide multiple return values, many function must return their results by writing into client-passed storage. Any pointer that is used to return a value is designated as such by the _return suf- fix as part of its name. All other pointers passed to these functions are used for reading only. By default, errors are handled either by a standard library function or by one that you provide. Functions that return pointers to strings will return NULL pointers if the string does not exist. Input events (for example, key pressed or mouse moved) __________________________ The <> has the meaning defined by the # include statement of the C compiler and is a file relative to a well known directory. On UNIX-based systems, this is /usr/include. December 18, 1987 - 4 - arrive asynchronously from the server and are queued until they are requested by a call to XNextEvent or XWindowEvent. In addition, some of the library functions (for example, XResizeWindow and XRaiseWindow) generate exposure events (that is, requests to repaint sections of a window that do not have valid contents). These events also arrive asynchro- nously, but the client may wish to explicitly wait for them by calling XSync after calling a function which may generate exposure events. 1.2. Naming and Argument Conventions within Xlib Throughout Xlib, a number of conventions for naming and syn- tax of the Xlib functions have been followed. These conven- tions are intended to make the syntax of the functions more predictable, given that you remember what information the routine may require. The major naming conventions are: o To better differentiate the X symbols from the user symbols, the library uses mixed case for external sym- bols, and leaves lower case for variables and all upper case for user macros, per existing convention. o All Xlib functions begin with a capital X. o The beginnings of all procedure names and symbols are capitalized. o All user-visible data structures begin with a capital X. More generally, anything that a user might derefer- ence begins with an capital X. o Macros and other symbols do not begin with a capital X. To distinguish them from all user symbols, each word in the macro is capitalized. o All elements of or variables in a data structure are in lower case. Compound words, where needed, are con- structed with underscores (_). o The display argument, where used, is always first in the argument list. o All resource objects, where used, occur at the begin- ning of the argument list, immediately after the display variable. o When a graphics context is present together with another type of resource (most commonly, a drawable), the graphics context occurs in the argument list after the other resource. Drawables outrank all other resources. December 18, 1987 - 5 - o Source arguments always precede the destination argu- ments in the argument list. o The x argument always precedes the y argument in the argument list. o The width argument always precedes the height argument in the argument list. o Where the x, y, width and height arguments are used together, the x and y arguments always precede the width and height arguments. o Where an array occurs in an argument list accompanied with a count (number of elements in the array), the array always precedes the count in the argument list. o Where a mask is accompanied with a structure, the mask always precedes the pointer to the structure in the argument list. 1.3. Programming Considerations The major considerations are: o Keyboards are the greatest variable between different manufacturer's workstations. If you want your program to be portable, you should be particularly conservative here. o Many display systems have limited amounts of off-screen memory. If you can, you should minimize use of pixmaps and backing store. o The user should have control of his screen real-estate. Therefore, you should write your applications to react to window management, rather than presume control of the entire screen. What you do inside of your top- level window, however, is up to your application. There is more on this topic elsewhere in the book. 1.4. Conventions Used in this Manual This manual is practical, descriptive guide to all the C language functions in the Xlib library. That is, it is organized by practical X programming tasks and describes each function in the library. All functions that are related to a given programming task are discussed in the same chapter or section, and each provides all the related background information that is needed for that discussion. Although you can read the chapters of this manual in any order, you should start by reading Chapter 2, which explains how to connect your display to the X server. December 18, 1987 - 6 - The major documentation conventions are: o Global symbols in this manual are printed in this spe- cial font. These can be either procedure names, sym- bols defined in include files, or structure names. Arguments, user-supplied variables, are printed in italics. o Most procedures are introduced by a general discussion that may be used to distinguish this procedure from other procedures and are followed by the procedure declaration itself. Each argument is then specifically explained. General discussion of the procedure, if any is required, follows the arguments. Where applicable, the last paragraph of given explanation lists the pos- sible Xlib error codes that can be generated by that function. See Section 8.10.2 for a complete discussion of the Xlib error codes. o To eliminate any ambiguity between those arguments that you pass and those that a function returns to you, the explanations for all arguments that you pass start with the word ``specifies''. By contrast, the explanations for all arguments that are returned to you start with the word ``returns''. December 18, 1987 - 7 - Chapter 2 Display Functions Chapter 2 - Opening and Closing the Display Before your pro- gram can use a display, you must establish a connection to the X server driving your display. Once you have esta- blished a connection, you then can use the Xlib macros and functions discussed in this chapter to return information about the display. This chapter discusses how to: o Open (connect) the display o Obtain information about the display, image formats, or a screen o Generate a NoOperation protocol request o Free client-created data o Close (disconnect) a display Finally, the chapter concludes with a section that describes the operations that occur when the connection to the X server is closed. 2.1. Opening the Display Use XOpenDisplay to open a connection to the X server con- trolling the specified display. X servers may implement various types of access control mechanisms. See section 7.11 for information about access control. The definition for this function is: Display *XOpenDisplay(display_name) char *display_name; display_nameSpecifies the hardware display name, which determines the display and communications domain to be used. On a UNIX-based system, if the display_name is NULL, it defaults to the DISPLAY environment variable. On all non-UNIX systems, see the Xlib manual associated with your operating system to determine the default for this argument. On UNIX-based systems, the display name or DISPLAY environ- ment variable is a string that has the format: December 18, 1987 - 8 - hostname:number.screen hostname Specifies the name of the host machine on which the display is physically attached. You follow the hostname with either a single colon (:) or a double colon (::). Each is discussed in the fol- lowing paragraph. number Specifies the number of the display server on that host machine. You may optionally follow this display number with a period (.). screen Specifies the number of the screen on that host server. Multiple screens can be connected to or controlled by a single X server. The screen sets an internal variable that can be accessed by using the DefaultScreen macro (or the XDefaultScreen function if you are using other languages). See Section 2.2.1 for further information. For example, the following would specify screen 2 of display 0 on the machine named mit-athena: mit-athena:0.2 The XOpenDisplay function returns a Display structure that serves as the connection to the X server and that contains all the information about that X server. XOpenDisplay con- nects the specified hardware display to the server through TCP, UNIX domain, or DECnet stream communications protocols. If the hostname is a host machine name and a single colon (:) separates the hostname and display number, XOpenDisplay connects using TCP streams. If the hostname is unix and a single colon (:) separates it from the display number, XOpenDisplay connects using UNIX domain IPC streams. If the hostname is a host machine name and a double colon (::) separates the hostname and display number, XOpenDisplay con- nects using DECnet streams. To use DECnet, however, the X library implementation must have been built to support it. A single server can support any or all of these transport mechanisms simultaneously. If successful, XOpenDisplay returns a pointer to a Display structure that is defined in <X11/Xlib.h>. See Section 2.2.1, for information about using macros and functions to obtain information from the Display structure. If XOpen- Display does not succeed, it returns a NULL. After a suc- cessful call to XOpenDisplay, all of the screens in the display may be used by the client application. The screen number specified in the display_name argument serves only to specify the value that will be returned by the DefaultScreen macro or the XDefaultScreen function. You can access ele- ments of the Display and Screen structures by using the December 18, 1987 - 9 - information macros or functions. 2.2. Obtaining Information About the Display, Image For- mats, or Screens The Xlib library provides a number of useful macros and corresponding functions that return data from the Display structure. The macros are to be used for C programming, while their corresponding function equivalents are for other language bindings. This section discusses the: o Display macros o Image format macros o Screen macros All other members of the Display structure (that is, those for which no macros are defined) are private to Xlib and must not be used. That is, applications must never directly modify or inspect these private elements in the Display structure. 2.2.1. Display Macros Once you have successfully connected to the X server that is driving a screen on your display, you can use the Xlib display macros or corresponding functions to obtain informa- tion about that display. Applications should not directly modify any part of the Display and Screen structures. The members should be considered read-only, although they may change as the result of other operations on the display. The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, and what data they both can return. AllPlanes() unsigned long XAllPlanes() Both return a value with all bits set on suitable for use in a plane argument to a procedure. BlackPixel(display, screen) unsigned long XBlackPixel(display, screen) Display *display; int screen; December 18, 1987 - 10 - Both return the black pixel value for the specified screen. ConnectionNumber(display) int XConnectionNumber(display) Display *display; Both return a connection number for the specified display. On a UNIX-based system, this is the file descriptor of the connection. DefaultColormap(display, screen) Colormap XDefaultColormap(display, screen) Display *display; int screen; Both return the default Colormap ID for allocation on the specified screen. Most routine allocations of color should be made out of this color map. DefaultDepth(display, screen) int XDefaultDepth(display, screen) Display *display; int screen; Both return the depth (number of planes) of the default root window for the specified screen. Other depths may also be supported on this screen. See XMatchVisualInfo in Chapter 10 to find out how to determine what depths may be avail- able. DefaultGC(display, screen) GC XDefaultGC(display, screen) Display *display; int screen; Both return the default graphics context for the root window of the specified screen. This GC is created for the con- venience of simple applications and contains the default GC December 18, 1987 - 11 - components with the foreground and background pixel values initialized to the black and white pixels, respectively, for the screen. You can modify its contents freely because it is not used in any Xlib function. DefaultRootWindow(display) Window XDefaultRootWindow(display) Display *display; Both return the root window for the default screen. DefaultScreen(display) int XDefaultScreen(display) Display *display; Both return the default screen referenced in the XOpen- Display routine. This macro and function should be used to retrieve the screen number in applications that will use only a single screen. DefaultVisual(display, screen) Visual *XDefaultVisual(display, screen) Display *display; int screen; Both return the default visual type for the specified screen. See section 3.1 for further information about visual types. DisplayCells(display, screen) int XDisplayCells(display, screen) Display *display; int screen; Both return the number of entries in the default color map. December 18, 1987 - 12 - DisplayPlanes(display, screen) int XDisplayPlanes(display, screen) Display *display; int screen; Both return the depth of the root window of the specified screen. See the glossary for a discussion of depth. DisplayString(display) char *XDisplayString(display) Display *display; Both return the string that was passed to XOpenDisplay when the current display was opened. On UNIX-based systems, if the passed string was NULL, this macro returns the value of the DISPLAY environment variable when the current display was opened. This macro is useful to applications that invoke the fork system call and want to open a new connec- tion to the same display from the child process. ImageByteOrder(display) int XImageByteOrder(display) Display *display; Both specify the required byte order for images for each scanline unit in XYFormat (bitmap) or for each pixel value in ZFormat. The macro and function can return one of the constants LSBFirst or MSBFirst. ProtocolRevision(display) int XProtocolRevision(display) Display *display; Both return the minor protocol revision number of the X server. December 18, 1987 - 13 - ProtocolVersion(display) int XProtocolVersion(display) Display *display; Both return the major version number (11) of the X protocol associated with the connected display. QLength(display) int XQLength(display) Display *display; Both return the length of the event queue for the connected display. Note that there may be more events that have not been read into the queue yet. RootWindow(display, screen) Window XRootWindow(display, screen) Display *display; int screen; Both return the root window. This macro and function are useful with functions that take a parent window as an argu- ment. ScreenCount(display) int XScreenCount(display) Display *display; Both return the number of available screens. ServerVendor(display) char *XServerVendor(display) Display *display; Both return a pointer to a null-terminated string that pro- vides some identification of the owner of the X server December 18, 1987 - 14 - implementation. VendorRelease(display) int XVendorRelease(display) Display *display; Both return a number related to a vendor's release of the X server. WhitePixel(display, screen) unsigned long XWhitePixel(display, screen) Display *display; int screen; Both return the white pixel value for the specified screen. 2.2.2. Image Format Macros Once you have successfully connected to the X server that is driving a screen on your display, you can use the Xlib image format macros to obtain information about image formats. The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, and what data they both return. These are often used by toolkits as well as simple applications. BitmapBitOrder(display) int XBitmapBitOrder(display) Display *display; Within each bitmap unit, the leftmost bit in the bitmap as displayed on the screen is either the least or most signifi- cant bit in the unit. This macro and function can return one of the constants LSBFirst or MSBFirst. BitmapPad(display) int XBitmapPad(display) Display *display; December 18, 1987 - 15 - Each scanline must be padded to a multiple of bits returned by this macro or function. BitmapUnit(display) int XBitmapUnit(display) Display *display; Both return the size of a bitmap's unit in bits. The scan- line is calculated in multiples of this value. DisplayHeight(display, screen) int XDisplayHeightMM(display, screen) Display *display; int screen; Both return an integer that describes the height of the screen in pixels. DisplayHeightMM(display, screen) int XDisplayHeightMM(display, screen) Display *display; int screen; Both return the height of the specified screen in millime- ters. DisplayWidth(display, screen) int XDisplayWidth(display, screen) Display *display; int screen; Both return an integer that describes the width of the screen in pixels. December 18, 1987 - 16 - DisplayWidthMM(display, screen) int XDisplayWidthMM(display, screen) Display *display; int screen; Both return the width of the specified screen in millime- ters. 2.2.3. Screen Information Macros Once you have successfully connected to the X server that is driving a screen on your display, you can use the Xlib screen information macros to obtain information about screens. The following lists the C language macros, their correspond- ing function equivalents that are for other language bind- ings, and what data they both can return. BlackPixelOfScreen(screen) unsigned long XBlackPixelOfScreen(screen) Screen *screen; Both return the black pixel value of the specified screen. CellsOfScreen(screen) int XCellsOfScreen(screen) Screen *screen; Both return the number of colormap cells of the specified screen. DefaultColormapOfScreen(screen) Colormap XDefaultColormapOfScreen(screen) Screen *screen; Both return the default colormap of the specified screen. December 18, 1987 - 17 - DefaultDepthOfScreen(screen) int XDefaultDepthOfScreen(screen) Screen *screen; Both return the default depth of the specified screen. DefaultGCOfScreen(screen) GC XDefaultGCOfScreen(screen) Screen *screen; Both return the default graphics context (GC) of the speci- fied screen. DefaultScreenOfDisplay(display) Screen *XDefaultScreenOfDisplay(display) Display *display; Both return the default screen of the specified display. DefaultVisualOfScreen(screen) Visual *XDefaultVisualOfScreen(screen) Screen *screen; Both return the default visual of the specified screen. See Section 3.1 for information on visual types. DoesBackingStore(screen) int XDoesBackingStore(screen) Screen *screen; Both return a value indicating whether the screen supports backing stores. The value returned can be one of the con- stants WhenMapped, NotUseful, or Always. See section 3.2.4 for a discussion of the backing store. December 18, 1987 - 18 - DoesSaveUnders(screen) Bool XDoesSaveUnders(screen) Screen *screen; Both return a boolean value indicating whether the screen supports save unders. If True, the screen supports save unders. If False, the screen does not support save unders. See section 3.2.6 for a discussion of the save under. DisplayOfScreen(screen) Display *XDisplayOfScreen(screen) Screen *screen; Both return the display of the specified screen. EventMaskOfScreen(screen) long XEventMaskOfScreen(screen) Screen *screen; Both return the initial root event mask for the specified screen. HeightOfScreen(screen) int XHeightOfScreen(screen) Screen *screen; Both return the height of the specified screen. HeightMMOfScreen(screen) int XHeightMMOfScreen(screen) Screen *screen; Both return the height of the specified screen in millime- ters. December 18, 1987 - 19 - MaxCmapsOfScreen(screen) int XMaxCmapsOfScreen(screen) Screen *screen; Both return the maximum number of color maps supported by the specified screen. MinCmapsOfScreen(screen) int XMinCmapsOfScreen(screen) Screen *screen; Both return the minimum number of color maps supported by the specified screen. PlanesOfScreen(screen) int XPlanesOfScreen(screen) Screen *screen; Both return the number of planes in the specified screen. RootWindowOfScreen(screen) Window XRootWindowOfScreen(screen) Screen *screen; Both return the root window of the specified screen. ScreenOfDisplay(display, screen_number) Screen *XScreenOfDisplay(display, screen_number) Display *display; int screen_number; Both return a pointer to the screen of the specified display. December 18, 1987 - 20 - WhitePixelOfScreen(screen) unsigned long XWhitePixelOfScreen(screen) Screen *screen; Both return the white pixel value of the specified screen. WidthOfScreen(screen) int XWidthOfScreen(screen) Screen *screen; Both return the width of the specified screen. WidthMMOfScreen(screen) int XWidthMMOfScreen(screen) Screen *screen; Both return the width of the specified screen in millime- ters. 2.3. Generating a NoOperation Protocol Request Use XNoOp to execute a NoOperation protocol request. The definition for this function is: XNoOp(display) Display *display; display Specifies the connection to the X server. The XNoOp function sends a NoOperation request to the X server, thereby exercising the connection. It does not flush the output buffer. 2.4. Freeing Client-Created Data Use XFree to free any in-memory data that was created by an Xlib function. The definition for this function is: XFree(data) char *data; December 18, 1987 - 21 - data Specifies a pointer to the data that is to be freed. The XFree function is a general purpose Xlib routine that frees the specified data. 2.5. Closing the Display Use XCloseDisplay to close or disconnect a display from the X server. The definition for this function is: XCloseDisplay(display) Display *display; display Specifies the connection to the X server. The XCloseDisplay function closes the connection to the X server for the display specified in the Display structure. The XCloseDisplay function destroys all windows, resource IDs (Window, Font, Pixmap, Colormap, Cursor, and GContext), or other resources (GCs) that the client application has created on this display, unless the closedown mode of the resource has been changed. Therefore, these windows, resource IDs, and other resources should never be referenced again. In addition, this function discards any output requests that have been buffered but have not yet been sent. Because these operations automatically (implicitly) occur if a process exits, you normally do not have to call XCloseDisplay explicitly. 2.6. X Server Connection Close Operations When the X server's connection to a client is closed, either by an explicit call to XCloseDisplay or by a process that exits, the X server performs these automatic operations: o All selections (see XSetSelectionOwner) owned by the client are disowned. o Performs an XUngrabPointer and XUngrabKeyboard if the client application has actively grabbed the pointer or the keyboard. These functions are described in Chapter 7. o Performs an XUngrabServer if the client has grabbed the server. This function is described in Chapter 7. o Releases all passive grabs made by the client applica- tion. December 18, 1987 - 22 - o Marks all resources (including color map entries) allo- cated by the client application either as permanent or temporary, depending on whether the close_mode argument is one of the constants RetainPermanent or RetainTem- porary. However, this does not prevent other client applications from explicitly destroying the resources. (See below and XSetCloseDownMode in Chapter 7 for further information.) When the mode is DestroyAll, the X server destroys all of a client application's resources as follows: o Examines each window in the client's save-set to deter- mine if it is an inferior (subwindow) of a window created by the client. (The save-set is a list of other clients windows, and windows in this list are referred to as a save-set window.) If so, the X server reparents the save-set window to the closest ancestor such that the save-set window is not an inferior of a window created by the client. o Performs a MapWindow request on the save-set window if the save-set window is unmapped. The X server does this even if the save-set window was not an inferior of a window created by the client. o Examines each window in the client's save-set, and des- troys all windows created by the client. o Performs the appropriate free request on each nonwindow resource created by the client in the server (for exam- ple, Font, Pixmap, Cursor, Colormap, and GContext). o Frees all colors and color map entries allocated by a client application. Additional processing occurs when the last connection to the X server closes. An X server goes through a cycle of having no connections and having some connections. When the last display connection to the X server closes as a result of a connection closing with the close_mode argument DestroyAll (that is, the X server reverts to the state of having no connections), the X server: o Resets its state, as if it had just been started. The X server begins by destroying all lingering resources from clients that have terminated in RetainPermanent or RetainTemporary mode. o Deletes all but the predefined atom identifiers. o Deletes all properties on all root windows. See Chapter 4 for information about properties. December 18, 1987 - 23 - o Resets all device maps and attributes (for example, key click, bell volume, and acceleration) and the access control list. o Restores the standard root tiles and cursors. o Restores the default font path. o Restores the input focus to state PointerRoot. However, the X server does not reset if you close a connec- tion with a close_down mode argument set to RetainPermanent or RetainTemporary. December 18, 1987 - 24 - Chapter 3 Window Related Operations Chapter 3 - Window Related Operations In the X window sys- tem, a window is a rectangular area on the screen that lets you view graphical output. Client applications can display overlapping and nested windows on one or more screens that are driven by X servers on one or more machines. Clients who want to create windows must first connect their program to the X server by calling the Xlib function XOpenDisplay. This chapter begins with a discussion of visual types and window attributes. The chapter continues with a discussion of the Xlib functions you can use to: o Create windows o Destroy windows o Map windows o Unmap windows o Configure windows o Change the stacking order o Change window attributes o Translate window coordinates Note Your application should seldom directly create windows, particularly top-level windows. If you use a toolkit, the toolkit will do most of your window-creating for you. See the documentation for your toolkit. This chapter also identifies the window actions that may generate events. See Chapter 8 for a complete discussion of events. 3.1. Visual Types On some high end displays, it may be possible to deal with color resources in more than one way. For example, you may be able to deal with the display either as a 12-bit display with arbitrary mapping of pixel to color (pseudo-color) or December 18, 1987 - 25 - as a 24-bit display with 8 bits of the pixel dedicated for red, green, and blue. These different ways of dealing with the visual aspects of the display are called Visuals. For each screen of the display, there may be a list of valid visual types supported at different depths of the display. Because there are default windows and visual types defined for each screen, most simple applications need not deal with this complexity. Xlib provides macros and functions that return the default root window, the default depth of the default root window, and the default visual type. See Chapter 2 for information on these macros and functions. See XMatchVisualInfo in Chapter 10 for information about how to find the visual type you need. Xlib uses a Visual structure that contains information about the possible color mapping. The members of this structure pertinent to this discussion are class, red_mask, green_mask, blue_mask, bits_per_rgb, and map_entries. The class member specifies the possible visual classes of the screen. It can be one of the constants StaticGray, Sta- ticColor, TrueColor, GrayScale, PseudoColor, or DirectColor. Conceptually, as each pixel is read out of memory, it goes through a lookup stage by indexing into a colormap. Color- maps can be manipulated arbitrarily on some hardware, in limited way on other hardware, and not at all on yet other hardware. The visual types affect the color map and the RGB values in the following ways: o For PseudoColor, a pixel value indexes a color map to produce independent RGB values, and the RGB values can be changed dynamically. o GrayScale is treated the same as PseudoColor, except the primary which drives the screen is undefined. Thus, the client should always store the same value for red, green, and blue in the color maps. o For DirectColor, a pixel value is decomposed into separate RGB subfields, and each subfield separately indexes the color map for the corresponding value. The RGB values can be changed dynamically. o TrueColor is treated the same as DirectColor, except the color map has predefined read-only RGB values. These RGB values are server-dependent, but provide (near-)linear ramps in each primary. o StaticColor is treated the same as PseudoColor, except the color map has predefined read-only server-dependent RGB values. December 18, 1987 - 26 - o StaticGray is treated the same as StaticColor, except the red, green, and blue values are equal for any sin- gle pixel value, thus resulting in shades of gray. Sta- ticGray with a two-entry colormap can be thought of as monochrome. The red_mask, green_mask, and blue_mask members are only defined for DirectColor and TrueColor. Each has one con- tiguous set of bits with no intersections. The bits_per_rgb member specifies the log base 2 of the approximate number of distinct color values (individually) of red, green, and blue. Actual RGB values are unsigned 16 bit numbers. The map_entries member defines the number of available color map entries in a newly created color map. For DirectColor and TrueColor, this will be the size of an individual pixel sub- field. The following concepts may serve to make the expla- nation of Visual types clearer. The screen can be color or grayscale. The screen can have a colormap that is writable or read-only. A screen can also have a colormap whose indices are decomposed into separate RGB pieces, provided one is not on a grayscale screen. This leads to the follow- ing diagram: Color GrayScale R/O R/W R/O R/W +-------------------------------+ Undecomposed |Static|Pseudo|Static |Gray | Colormap |Color|Color |Gray |Scale| +-------------------------------+ Decomposed |True |Direct| Colormap |Color|Color| +---------------+ 3.2. Window Attributes All windows have a border width of zero or more pixels, an optional background, an input mask, an event suppression mask, and a property list. The window border and background can be a solid color or a pattern, called a tile. All win- dows except the root have a parent and are clipped by their parent. If a window is stacked on top of another window, it obscures that other window for the purpose of input. If a window has a background (almost all do), it obscures the other window for purposes of output. Attempts to output to the obscured area will do nothing, and no input events (for example, pointer motion) will be generated for the obscured area. Windows classified as InputOnly have only the following attributes defined: December 18, 1987 - 27 - o win_gravity o event_mask o do_not_propagate_mask o override_redirect o cursor A BadMatch error is generated if you specify any other attributes for an InputOnly window. Windows have borders of a programmable width and pattern as well as a background pattern or tile. Pixels can be used for solid colors. In a program, you refer to the window using its resource ID of type Window. The background and border pixmaps may be destroyed immediately after creating the window if no further explicit references to them are to be made. A window's background pattern can be either a solid color or a pattern. The pattern can either be relative to the parent or absolute. If relative to the parent, the pattern will be shifted appropriately to match the parent window. If abso- lute, the pattern will be positioned in the window indepen- dently of the parent window. When windows are first created, they are not visible on the screen. Any output to a window not visible (not mapped) on the screen will be discarded. An application may wish to create a window long before it is mapped to the screen. When a window is eventually mapped to the screen (using XMapWindow), the X server will generate an exposure event for the window. A window manager may override your choice as to size, border width, and style for a window. Your program must be prepared to use the actual size and position of the top win- dow, which is reported when the window is first mapped. It is not acceptable for a client application to resize itself unless in direct response to a human command to do so. Instead, your program should either use the space given to it, or, if the space is too small for any useful work, your program might ask the user to resize the window. The border of your top-level windows are considered fair game for win- dow managers. The following symbols and the XSetWindowAttributes structure are used in the functions that follow. December 18, 1987 - 28 - #define CWBackPixmap (1L<<0) #define CWBackPixel (1L<<1) #define CWBorderPixmap (1L<<2) #define CWBorderPixel (1L<<3) #define CWBitGravity (1L<<4) #define CWWinGravity (1L<<5) #define CWBackingStore (1L<<6) #define CWBackingPlanes (1L<<7) #define CWBackingPixel (1L<<8) #define CWOverrideRedirect (1L<<9) #define CWSaveUnder (1L<<10) #define CWEventMask (1L<<11) #define CWDontPropagate (1L<<12) #define CWColormap (1L<<13) #define CWCursor (1L<<14) typedef struct { Pixmap background_pixmap;/* background, None, or ParentRelative */ unsigned long background_pixel;/* background pixel */ Pixmap border_pixmap; /* border of the window */ unsigned long border_pixel;/* border pixel value */ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes;/* planes to be preserved if possible */ unsigned long backing_pixel;/* value to use in restoring planes */ Bool save_under; /* should bits under be saved? (popups) */ long event_mask; /* set of events that should be saved */ long do_not_propagate_mask;/* set of events that should not propagate */ Bool override_redirect; /* boolean value for override_redirect */ Colormap colormap; /* color map to be associated with window */ Cursor cursor; /* cursor to be displayed (or None) */ } XSetWindowAttributes; The XSetWindowAttributes structure members are discussed in the following sections. 3.2.1. The background_pixmap and background_pixel Members The background_pixmap member specifies the pixmap to be used for a window's background. This pixmap can be of any size, although some sizes may be faster than others. The background_pixel member specifies a pixel value used to paint a window's background in a single color. You can set the background_pixmap member to a pixmap, the constant None, or the constant ParentRelative. The default value is the constant None. You can set the background_pixel to any pixel value. The default value is undefined. If you specify a background_pixel, it overrides either the default background_pixmap or any value you may have set in the background_pixmap member. All pixels in the December 18, 1987 - 29 - background of the window will be set to this value. If you set the background_pixmap, it overrides the default background_pixmap. The background_pixmap and the window must have the same depth. Otherwise, a BadMatch error is returned. If you set background_pixmap to None, the window has no defined background. If the parent window has a background_pixmap of None, the window will also have a background_pixmap of None. If you set the background_pixmap to ParentRelative: o The parent window's background_pixmap is used, but the child window must have the same depth as its parent. Otherwise, a BadMatch error is returned. o A copy of the parent window's background_pixmap is not made. The parent's background_pixmap is examined each time the child window background_pixmap is required. o The background tile origin always aligns with the parent window's background tile origin. Otherwise, the background tile origin is always the child window ori- gin. Setting a new background, whether by setting background_pixmap or background_pixel, overrides any previ- ous border. The background_pixmap can be freed immediately if no further explicit reference is made to it (the X server will keep a copy to use when needed). If you later draw into the pixmap used for the background, X does not predict what happens because the X implementation is free to either make a copy of the pixmap or just use the same pixmap. When regions of the window are exposed and the X server has not retained the contents, it automatically tiles the regions with the window's background as long as the background_pixmap is not None. If the background_pixmap is None, the previous screen contents are left in place if the window and its parent are the same depth. Otherwise, the initial contents of the exposed regions are undefined. Exposure events are then generated for the regions, even if the background_pixmap is None. See Chapter 8 for a discus- sion of exposure event processing. 3.2.2. The border_pixmap and border_pixel Members The border_pixmap member specifies the pixmap to be used for a window's border. This pixmap can be of any size, although some sizes may be faster than others. The border_pixel member specifies a pixmap of undefined size be used for a window's border. The border tile origin is always the same as the background tile origin. You can also set border_pixmap to CopyFromParent. In this December 18, 1987 - 30 - case, the pixmap used for the border will be a copy of the parent window's border pixmap. The default value is the constant CopyFromParent. You can set the border_pixel to any pixel value. The default value is undefined. If you specify a border_pixel, it overrides either the default border_pixmap or any value you may have set in the border_pixmap member. All pixels in the window's border will be set to the border_pixel value. Setting a new border, whether by setting border_pixel or by setting border_pixmap overrides any previous border. If you set a border_pixmap value, it overrides the default border_pixmap. The border_pixmap and the window must have the same depth. Otherwise, a BadMatch error is returned. If you set the border_pixmap to the constant CopyFromParent, the parent window's border_pixmap is copied. Subsequent changes to the parent window do not affect the child window. However, the child window must have the same depth as the parent window. Otherwise, a BadMatch error is returned. The border_pixmap can be freed immediately if no further explicit reference is made to it. If you later draw into the pixmap used for the border, X does not predict what hap- pens because the X implementation is free to either make a copy of the pixmap or use the same pixmap each time the win- dow border is repainted. Output to a window is always clipped to the inside of the window. Therefore, graphics operations never affect the win- dow border. Borders are added to the window size specified. 3.2.3. The bit_gravity and win_gravity Members Bit gravity defines which region of the window should be retained when the window is resized. The default value for the bit_gravity member is the constant ForgetGravity. Win- dow gravity allows you to define how the window should be repositioned if its parent is resized. The default value for the win_gravity member is the constant NorthWestGravity. See XGetWindowAttributes in Section 4.1 for a description of the possible values you can set these to. 3.2.4. The backing_store Member Some implementations of the X server may choose to maintain the contents of windows. If the X server maintains the con- tents of a window, the off-screen saved pixels are known as backing store. The backing_store member advises the X server on what to do with the contents of a window. You can set this member to NotUseful, WhenMapped, or Always. The default value is NotUseful. A backing_store of WhenMapped advises the X server that maintaining contents of obscured regions when the window is December 18, 1987 - 31 - mapped would be beneficial. A backing_store of Always advises the X server that maintaining contents even when the window is unmapped would be beneficial. Even if the window is larger than its parent, this is a request to the X server to maintain complete contents, not just the region within the parent window boundaries. If the X server maintains con- tents, exposure events will not be generated, but the X server may stop maintaining contents at any time. A backing_store of NotUseful advises the X server that main- taining contents is unnecessary, although some X implementa- tions may still choose to maintain contents and, therefore, not generate exposure events. 3.2.5. The backing_planes and backing_pixel Members The default value for the backing_planes member is all ones. It indicates (with one bits) which bit planes of the window hold dynamic data that must be preserved in backing_stores and during save_unders. The default value for the backing_pixel member is zero (0). It specifies what values to use in planes not covered by backing_planes. The X server is free to save only the specified bit planes in the backing_store or the save_under and is free to regenerate the remaining planes with the specified pixel value. Any extraneous bits (that is, those beyond the specified depth of the window) in these values may be simply ignored. 3.2.6. The save_under Member Some server implementations may preserve bits of windows under other windows. This is not the same as preserving the contents of a window for you. You may get better visual appeal if transient windows (for example, pop-up menus) request that the system preserve the bits under them, so the temporarily obscured applications do not have to repaint. The default value for the save_under member is False. If save_under is True, the X server is advised that, when this window is mapped, saving the contents of windows it obscures would be beneficial. 3.2.7. The event_mask and do_not_propagate_mask Members The event_mask defines which events the client is interested in for this window (or, for some event types, inferiors of the window). The do_not_propagate_mask defines which events should not be propagated to ancestor windows when no client has the event type selected in this window. These masks are the bitwise inclusive OR of one or more of the valid event mask bits. You can specify that no maskable events are reported by passing the constant NoEventMask. The default value for these members is the empty set. See Section 8.3 for information on the event mask and events. December 18, 1987 - 32 - 3.2.8. The override_redirect Member The default value for the override_redirect member is False. Override_redirect specifies whether map and configure requests on this window should override a Substruc- tureRedirectMask on the parent. Window manages use this information to avoid tampering with pop-up windows. 3.2.9. The colormap Member The default value for the colormap member is CopyFromParent. The colormap member specifies which color map, if any, best reflects the true colors of the window. The colormap must have the same visual type as the window. Otherwise, a Bad- Match error is returned. X servers capable of supporting multiple hardware color maps may use this information, and window managers may use it for InstallColormap requests. If you set the colormap member to CopyFromParent, the parent window's color map is copied and used by its child. Subse- quent changes to the parent window do not affect the child window. However, the child window must have the same visual type as the parent. Otherwise, a BadMatch error is returned. The parent window must not have a color map of None. Other- wise, a BadMatch error is returned. 3.2.10. The cursor Member The default value for the cursor member is the constant None. If a cursor is specified, it will be used whenever the pointer is in the window. If None is specified, the parent's cursor will be used when the pointer is in the win- dow, and any change in the parent's cursor will cause an immediate change in the displayed cursor. The cursor may be freed immediately if no further explicit reference to it is made by calling XFreeCursor. See Section 6.8.2 for further information. 3.2.11. Default Values for XSetWindowAttributes Members The following table lists the default values for each member in the XSetWindowAttributes structure. ________________________________________ Member Default Value ________________________________________ background_pixmap None background_pixel Undefined border_pixmap CopyFromParent border_pixel Undefined bit_gravity ForgetGravity win_gravity NorthWestGravity backing_store NotUseful backing_planes All ones backing_pixel 0 (zero) December 18, 1987 - 33 - ________________________________________ Member Default Value ________________________________________ save_under False event_mask empty set do_not_propagate_mask empty set override_redirect False colormap CopyFromParent cursor None ________________________________________ 3.3. Creating Windows Xlib provides basic ways of creating windows. See the X toolkit documentation for more information. If you create your own top level windows (direct children of the root win- dow) the rules enumerated below must be observed for appli- cations to interact reasonably across differing styles of window management. You should never fight with a window manager for size or placement of your top-level window(s). Toolkits often sup- ply routines specifically for creating and placing top level windows. If you do not use a toolkit, you should provide some standard information or ``hints'' to the window manager by using the utility functions described in Chapter 10. The policy guidelines for window creation are: 1. An application, by listening to the first exposure event, must be able to deal with whatever size window it gets, even if this means that the application just prints a message, like ``Please make me bigger,'' in its window. 2. An application should only attempt to resize or move its top-level window in direct response to a user request. An application is free to resize or move the children of its top-level window as necessary. (Toolk- its often have facilities for automatic relayout.) If a request to change the size of its top-level window fails, the application must not fight with the window manager. 3. If an application does not use a toolkit that automati- cally sets standard window properties, that application should set these properties for the top-level window before mapping it. To set standard window properties for a top-level window, use XSetStandardProperties. See Chapter 9 for further information. The low-level functions provided by Xlib to create an unmapped subwindow for a specified parent window are December 18, 1987 - 34 - XCreateWindow and XCreateSimpleWindow. XCreateWindow is a more general function that allows you to set specific window attributes when you create it. XCreateSimpleWindow creates a window that inherits its attributes from its parent win- dow. That is, you do not set specific attributes when you create a simple window. The X server acts as if InputOnly windows do not exist for the purposes of graphics requests, exposure processing, and VisibilityNotify events. An InputOnly window cannot be used as a drawable (that is, as a source or destination for graphics requests). InputOnly and InputOutput windows act identically in other respects (properties, grabs, input con- trol, and so on). Extension packages may define other classes of windows. The definition for XCreateWindow is: Window XCreateWindow(display, parent, x, y, width, height, border_width, depth, class, visual, valuemask, attributes) Display *display; Window parent; int x, y; unsigned int width, height; unsigned int border_width; int depth; unsigned int class; Visual *visual unsigned long valuemask; XSetWindowAttributes *attributes; display Specifies the connection to the X server. parent Specifies the parent window ID. x y Specify the x and y coordinates. These coordi- nates are the top left outside corner of the created window's borders and are relative to the inside of the parent window's borders. width height Specify the width and height. These are the created window's inside dimensions. These dimen- sions do not include the created window's borders, which are entirely outside of the window. The dimensions must be nonzero. Otherwise, a BadValue error is returned. border_widthSpecifies, in pixels, the width of the created window's border. The border_width for an Inpu- tOnly window must be zero (0). Otherwise, a Bad- Match error is returned. December 18, 1987 - 35 - depth A depth of zero for class InputOutput or CopyFrom- Parent means the depth is taken from the parent. class Specifies the created window's class. You can pass one of these constants: InputOutput, Inpu- tOnly, or CopyFromParent. A class of CopyFrom- Parent means the class is taken from the parent. visual Specifies the visual type. A visual of CopyFrom- Parent means the visual type is taken from the parent. valuemask Specifies which window attributes are defined in the attributes argument. This mask is the bitwise inclusive OR of the valid attribute mask bits. If valuemask is zero (0), the rest is ignored, and the attributes are not referenced. attributesAttributes of the window to be set at creation time should be set in this structure. The valuemask should have the appropriate bits set to indicate which attributes have been set in the structure. See Section 3.2 for further informa- tion. The XCreateWindow function creates an unmapped subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings. For class InputOutput, the visual type and depth must be a combination supported for the screen. Otherwise, a BadMatch error is returned. The depth need not be the same as the parent, but the parent must not be a window of class Inpu- tOnly. Otherwise, a BadMatch error is generated. For an InputOnly window the depth must be zero (0), and the visual must be one supported by the screen. If either of these conditions are not met, a BadMatch error is generated. The parent window, however, may have any depth and class. The only window attributes defined for InputOnly windows are win_gravity, event_mask, do_not_propagate_mask, override_redirect, and cursor. If you specify any other window attribute for an InputOnly window, a BadMatch error is returned. The errors that can be generated by XCreateWindow are BadAl- loc BadColor, BadCursor, BadMatch, BadPixmap, BadValue, and BadWindow. Use XCreateSimpleWindow to create an unmapped InputOutput subwindow of the specified parent window. The definition for this function is: December 18, 1987 - 36 - Window XCreateSimpleWindow(display, parent, x, y, width, height, border_width, border, background) Display *display; Window parent; int x, y; unsigned int width, height, border_width; unsigned long border; unsigned long background; display Specifies the connection to the X server. parent Specifies the parent window ID. x y Specify the x and y coordinates. These coordi- nates are the top left outside corner of the new window's borders and are relative to the inside of the parent window's borders. width height Specify the width and height. These are the created window's inside dimensions. These dimen- sions do not include the created window's borders, which are entirely outside of the window. The dimensions must be nonzero. Otherwise, a BadValue error is returned. border_widthSpecifies, in pixels, the width of the created window's border. The border_width for an Inpu- tOnly window must be zero (0). Otherwise, a Bad- Match error is returned. border Specifies the border pixel of the window. backgroundSpecifies the pixel value that you want to set for the specified window's background. The XCreateSimpleWindow function creates an unmapped Inpu- tOutput subwindow for a specified parent window, returns the window ID of the created window, and causes the X server to generate a CreateNotify event. The created window is placed on top in the stacking order with respect to siblings. Any part of the window that extends outside its parent window will be clipped. XCreateSimpleWindow inherits its depth, class, and visual from its parent. All other window attri- butes have their default values. The created window is not yet displayed (mapped) on the user's display. To display the window, call XMapWindow. The new window will initially use the same cursor as its parent. A new cursor may, of course, be defined for the new window by calling XDefineCursor. The window will not be December 18, 1987 - 37 - visible on the screen unless it and all of its ancestors are mapped, and it is not obscured by any of its ancestors. The window is placed on top of the stacking order with respect to its siblings. In addition, the new window's cursor will be None. The errors that can be generated by XCreateSimpleWindow are BadAlloc, BadValue, and BadWindow. 3.4. Destroying Windows Xlib provides functions with which you can destroy a window or destroy all subwindows of a window. Use XDestroyWindow to destroy a window and all of its subwindows. The definition for this function is: XDestroyWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XDestroyWindow function destroys the specified window as well as all of its subwindows and causes the X server to generate a DestroyNotify event for each window. The window should never again be referenced. If the window specified by the w argument is mapped, it is unmapped automatically. The window and all of its inferiors are then destroyed, and a DestroyNotify event is generated for each window. The ordering of the DestroyNotify events is such that for any given window being destroyed, DestroyNotify is generated on any inferiors of the window before being generated on the window itself. The ordering among siblings and across subhierarchies is not otherwise constrained. If the window you specified is a root window, no windows are destroyed. Destroying a mapped window will generate exposure events on other windows that were obscured by the window being des- troyed. The error that can be generated by XDestroyWindow is BadWin- dow. Use XDestroySubwindows to destroy all subwindows of a speci- fied window. The definition for this function is: XDestroySubwindows(display, w) Display *display; Window w; December 18, 1987 - 38 - display Specifies the connection to the X server. w Specifies the window ID. The XDestroySubwindows function destroys all inferior win- dows of the specified window, in bottom to top stacking order. It causes the X server to generate a DestroyNotify event for each window. If any mapped subwindows were actu- ally destroyed, XDestroySubwindows causes the X sever to generate exposure events on the specified window. This is much more efficient than deleting many windows one at a time because much of the work need only be performed once for all of the windows rather than for each window. The subwindows should never again be referenced. The error that can be generated by XDestroySubwindows is BadWindow. Note XCloseDisplay automatically destroys all windows that have been created on that server if it is the last copy of the connection. (Remember that under UNIX, fork will duplicate open connections). 3.5. Mapping Windows A window manager may want to control the placement of subwindows. If SubstructureRedirectMask has been selected by a window manager on a parent window (usually a root win- dow), a map request initiated by other clients on a child window is not performed, and the window manager would be sent a MapRequest event. However, if the override_redirect flag on the child had been set to True (usually only on pop-up menus), the map request would be performed. A tiling window manager might decide to reposition and resize other client's windows and then decide to map the window at its final location. A window manager that wants to provide decoration might reparent the child into a frame first. See Section 3.2.7 and Chapter 8 for further informa- tion. Only a single client at a time can select for Sub- structureRedirectMask. Similarly, a single client can select for ResizeRedirectMask on a parent window. Then, any attempt to resize the window is suppressed, and the client (usually, a window manager) receives a ResizeRequest event. These mechanisms allow arbitrary placement policy to be enforced by an external window manager. A window is considered mapped if a XMapWindow call has been made on it. It may not be visible on the screen for one of December 18, 1987 - 39 - the following reasons: o It is obscured by another opaque sibling window. o One of its ancestors is not mapped. o It is entirely clipped by an ancestor. Exposure events will be generated for the window when part or all of it becomes visible on the screen. A client will only receive the exposure events if it has asked for them using XSelectInput. Windows retain their position in the stacking order when unmapped. Use XMapWindow to map the specified window. The definition for this function is: XMapWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XMapWindow function maps the window and all of its subwindows which have had map requests. A subwindow will appear on the screen as long as all of its ancestors are mapped and not obscured by a sibling or are not clipped by an ancestor. Mapping a window that has an unmapped ancestor does not display the window but marks it as eligible for display when the ancestor becomes mapped. Such a window is called unviewable. When all its ancestors are mapped, the window becomes viewable and will be visible on the screen if it is not obscured by any sibling or ancestor. This func- tion has no effect if the window is already mapped. If the override_redirect member of the XSetWindowAttributes structure is False, and if some other client has selected SubstructureRedirectMask on the parent window, then the X server generates a MapRequest event, and the XMapWindow function does not map the window. Otherwise, the window is mapped, and the X server generates a MapNotify event. If the window becomes viewable and no earlier contents for it are remembered, XMapWindow tiles the window with its background. If no background was defined for the window, the existing screen contents are not altered, and the X server generates one or more Expose events. If a backing_store was maintained while the window was unmapped, no Expose events are generated. If a backing_store will now be maintained, a full-window exposure is always generated. December 18, 1987 - 40 - Otherwise, only visible regions may be reported. Similar tiling and exposure take place for any newly viewable infe- riors. If the window is an InputOutput window, XMapWindow generates Expose events on each InputOutput window that it causes to become displayed. If the client maps and paints the window, and if the client begins processing events, the window will be painted twice. To avoid this, the client should call XSelectInput for exposure events, and map the window. Then, the client should process input events normally. The event list will include Expose for each window that has appeared on the screen. The client's normal response to an Expose event should be to repaint the window. This method usually leads to simpler programs and to proper interaction with window managers. The error that can be generated by XMapWindow is BadWindow. Use XMapRaised to map and raise a window. The definition for this function is: XMapRaised(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XMapRaised function essentially is similar to XMapWindow in that it maps the window and all of its subwindows which have had map requests. However, it also raises the speci- fied window to the top of the stack. See the XMapWindow description for additional information. The error that can be generated by XMapRaised is BadWindow. Use XMapSubwindows to map all subwindows for a specified window. The definition for this function is: XMapSubwindows(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XMapSubwindows function maps all subwindows for a December 18, 1987 - 41 - specified window in top-to-bottom stacking order. The X server to generate an Expose event on each newly displayed window. This is much more efficient than mapping many win- dows one at a time, because the server needs only perform much of the work once for all of the windows rather than for each window. The error that can be generated by XMapSubwindows is BadWin- dow. 3.6. Unmapping Windows Xlib provides functions with which you can unmap a window or all subwindows. Use XUnmapWindow to unmap a window. The definition for this function is: XUnmapWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XUnmapWindow function unmaps the specified window and causes the X server to generate an UnmapNotify event. If the specified window is already unmapped, XUnmapWindow has no effect. Normal exposure processing on formerly obscured windows is performed. Any child window will no longer be visible until another map call is made on the parent. In other words, the subwindows are still mapped but not visible until the parent is mapped. Unmapping a window will gen- erate exposure events on windows that were formerly obscured by it and its children. The error that can be generated by XUnmapWindow is BadWin- dow. Use XUnmapSubwindows to unmap all subwindows for a specified window. The definition for this function is: XUnmapSubwindows(display, w) Display *display; Window w; display Specifies the connection to the X server. December 18, 1987 - 42 - w Specifies the window ID. The XUnmapSubwindows function unmaps all subwindows for the specified window in bottom to top stacking order. It causes the X server to generate an UnmapNotify event on each subwindow and exposure events on formerly obscured windows. Using this function is much more efficient than unmapping multiple windows one at a time, because the server needs only perform much of the work once for all of the windows rather than for each window. The error that can be generated by XUnmapSubwindows is BadWindow. 3.7. Configuring Windows Xlib provides functions with which you can move a window, resize a window, move and resize a window, or change a window's border width. The most general interface to confi- guring windows, XConfigureWindow, uses the XWindowChanges structure, which contains: #define CWX (1<<0) #define CWY (1<<1) #define CWWidth (1<<2) #define CWHeight (1<<3) #define CWBorderWidth (1<<4) #define CWSibling (1<<5) #define CWStackMode (1<<6) typedef struct { int x, y; int width, height; int border_width; Window sibling; int stack_mode; } XWindowChanges; The following paragraphs discuss the members of this struc- ture and the processing that occurs for XConfigureWindow. The x and y members specify the x and y coordinates relative to the parent's origin and indicate the position of the upper left outer corner of the window. The width and height members specify the inside size of the window, not including the border. These arguments must be nonzero. Otherwise, a BadValue error is generated. Attempts to configure a root window have no effect. The border_width member specifies the width of the border in pixels. Note that changing just the border_width leaves the outer-left corner of the window in a fixed position, but moves the absolute position of the window's origin. A December 18, 1987 - 43 - BadMatch error is generated if you attempt to make the border_width of an InputOnly window nonzero. The sibling member specifies the sibling window for stacking operations. The stack_mode member can be one of these con- stants: Above, Below, TopIf, BottomIf, or Opposite. If the override_redirect attribute of the window is False, and if some other client has selected Substruc- tureRedirectMask on the parent, then the X server generates a ConfigureRequest event, and no further processing is per- formed. Otherwise, if some other client has selected Resiz- eRedirectMask on the window and the inside width or height of the window is being changed, a ResizeRequest event is generated, and the current inside width and height are used instead in the following. Note that the override_redirect attribute of the window has no effect on ResizeRedirectMask and that SubstructureRedirectMask on the parent has pre- cedence over ResizeRedirectMask on the window. The geometry of the window is changed as specified, the win- dow is restacked among siblings, and a ConfigureNotify event is generated. X generates GravityNotify events after gen- erating ConfigureNotify events. If the inside width or height of the window has actually changed, then children of the window are affected as described below. Exposure processing is performed on formerly obscured win- dows, including the window itself and its inferiors, if regions of them were obscured but now are not. As a result of increasing the width or height, exposure processing is also performed on any new regions of the window and any regions where window contents are lost. If the inside width or height of a window is not changed, and if the window is moved or its border is changed, then the contents of the window are not lost but move with the window. Changing the inside width or height of the window causes its contents to be moved or lost, depending on the bit_gravity of the window, and causes children to be recon- figured, depending on their win_gravity. For a change of width and height, the (x, y) pairs are defined: _______________________________________ Gravity Direction Coordinates _______________________________________ NorthWestGravity (0, 0) NorthGravity (Width/2, 0) NorthEastGravity (Width, 0) WestGravity (0, Height/2) CenterGravity (Width/2, Height/2) December 18, 1987 - 44 - EastGravity (Width, Height/2) SouthWestGravity (0, Height) SouthGravity (Width/2, Height) SouthEastGravity (Width, Height) _______________________________________ When a window with one of these bit_gravities is resized, the corresponding pair defines the change in position of each pixel in the window. When a window with one of these win_gravities has its parent window resized, the correspond- ing pair defines the change in position of the window within the parent. When a window is so repositioned, a GravityNo- tify event is generated. A bit_gravity of StaticGravity indicates that the contents or origin should not move relative to the origin of the root window. If the change in size of the window is coupled with a change in position (x, y), then for bit_gravity the change in position of each pixel is (-x, -y), and for win_gravity the change in position of a child when its parent is so resized is (-x, -y). Note that StaticGravity still only takes effect when the width or height of the window is changed, not when the window is moved. A bit_gravity of ForgetGravity indicates that the window's contents are always discarded after a size change, even if a backing_store or save_under has been requested. The window is tiled with its background and one or more exposure events are generated. If no background is defined, the existing screen contents are not altered. Some X servers may also ignore the specified bit_gravity and always generate expo- sure events. A win_gravity of UnmapGravity is like NorthWest (the window is not moved), but the child is also unmapped when the parent is resized, and an UnmapNotify event is generated. X generates GravityNotify notify events after generating Con- figureNotify events. A win_gravity of AntiGravity indicates all pixels should move radically outward from the center of the window._ The restack check (specifically, the computation for Bot- tomIf, TopIf, and Opposite) is performed with respect to the window's final size and position (as controlled by the other arguments to the request), not its initial position. It is an error if a sibling is specified without a stack_mode. If a sibling and a stack_mode are specified, the window is restacked as follows: __________________________ _ (If you believe this statement, there is a bridge for sale.) December 18, 1987 - 45 - Above The window is placed just above the sibling. Below The window is placed just below the sibling. TopIf If the sibling occludes the window, the window is placed at the top of the stack. BottomIf If the window occludes the sibling, the window is placed at the bottom of the stack. Opposite If the sibling occludes the window, the window is placed at the top of the stack. Otherwise, if the window occludes the sibling, the window is placed at the bottom of the stack. If a stack_mode is specified but no sibling is specified, the window is restacked as follows: Above The window is placed at the top of the stack. Below The window is placed at the bottom of the stack. TopIf If any sibling occludes the window, the window is placed at the top of the stack. BottomIf If the window occludes any sibling, the window is placed at the bottom of the stack. Opposite If any sibling occludes the window, the window is placed at the top of the stack. Otherwise, if the window occludes any sibling, the window is placed at the bottom of the stack. Use XConfigureWindow to reconfigure a window's size, posi- tion, border, and stacking order. The definition for this function is: XConfigureWindow(display, w, value_mask, values) Display *display; Window w; unsigned int value_mask; XWindowChanges *values; display Specifies the connection to the X server. w Specifies the window ID. This is the window to be reconfigured. value_maskSpecifies which values are to be set using infor- mation in the values structure. This mask is the bitwise inclusive OR of the valid change window values bits. December 18, 1987 - 46 - values Specifies a pointer to the structure XWin- dowChanges. The XConfigureWindow function uses the values specified in the XWindowChanges structure to reconfigure a window's size, position, border, and stacking order. The stacking order of the window is controlled by the function's arguments. Values not specified are taken from the existing geometry of the window. A BadMatch error is generated if a sibling is specified without a stack_mode or if the window is not actually a sibling. Note that the computations for BottomIf, TopIf, and Opposite are performed with respect to the window's final geometry (as controlled by the other arguments passed to XConfigureWindow), not its initial geometry. Any backing-store contents of the window, its inferiors, and other newly visible windows are either discarded or changed to reflect the current screen contents (implementation dependent). The errors that can be generated by XConfigureWindow are BadWindow, BadMatch, and BadValue. Use XMoveWindow to move a window without changing its size. The definition for this function is: XMoveWindow(display, w, x, y) Display *display; Window w; int x, y; display Specifies the connection to the X server. w Specifies the window ID. This is the window to be moved. x y Specify the x and y coordinates. These coordi- nates define the new location of the top left pixel of the window's border or the window itself, if it has no border. The XMoveWindow function moves the specified window to the specified x and y coordinates. This function does not change the window's size, does not raise the window, and does not change the mapping state of the window. Moving a mapped window may or may not lose its contents depending on: o If its tile mode is relative December 18, 1987 - 47 - o If the window is obscured by nonchildren If the contents of the window are lost, exposure events will be generated for the window and any mapped subwindows. Mov- ing a mapped window will generate exposure events on any formerly obscured windows. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, a ConfigureRequest event is generated, and no further processing is performed. Otherwise, the window is moved. The error that can be generated by XMoveWindow is BadWindow. Use XResizeWindow to change a window's size without changing the upper left coordinate. The definition for XResizeWindow is: XResizeWindow(display, w, width, height) Display *display; Window w; unsigned int width, height; display Specifies the connection to the X server. w Specifies the window ID. width height Specify the width and height. These are the dimensions of the window after the call completes. The XResizeWindow function changes the inside dimensions of the specified window, not including its borders. This func- tion does not change the window's upper-left coordinate or the origin and does not raise the window. Changing the size of a mapped window may lose its contents and generate an Expose event. If a mapped window is made smaller, exposure events will be generated on windows that it formerly obscured. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, a ConfigureRequest event is generated, and no further processing is performed. The error that can be generated by XResizeWindow is BadWin- dow. Use XMoveResizeWindow to change the size and location of a window. The definition for this function is: December 18, 1987 - 48 - XMoveResizeWindow(display, w, x, y, width, height) Display *display; Window w; int x, y; unsigned int width, height; display Specifies the connection to the X server. w Specifies the window ID. This is the window to be reconfigured. x y Specify the x and y coordinates. These coordi- nates define the new position of the window rela- tive to its parent. width height Specify the width and height. These arguments define the interior size of the window. The XMoveResizeWindow function changes the size and location of the specified window without raising it. Moving and resizing a mapped window may generate an Expose event on the window. Depending on the new size and location parameters, moving and resizing a window may generate exposure events on windows that the window formerly obscured. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, then a ConfigureRequest event is generated, and no further processing is performed. Otherwise, the win- dow size and location is changed. The errors that can be generated by XMoveResizeWindow are BadWindow, BadMatch, and BadValue. Use XSetWindowBorderWidth to change the border width of a window. The definition for this function is: XSetWindowBorderWidth(display, w, width) Display *display; Window w; unsigned int width; display Specifies the connection to the X server. w Specifies the window ID. width Specifies the width of the window border. The XSetWindowBorderWidth function sets the specified December 18, 1987 - 49 - window's border width to the specified width. The errors that can be generated by XSetWindowBorderWidth are BadWindow and BadValue. 3.8. Changing Window Stacking Order Xlib provides functions with which you can raise, lower, circulate, or restack windows. Use XRaiseWindow to raise a window so that no sibling window obscures it. The definition for this function is: XRaiseWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XRaiseWindow function raises the specified window to the top of the stack so that no sibling window obscures it. If the windows are regarded as overlapping sheets of paper stacked on a desk, then raising a window is analogous to moving the sheet to the top of the stack but leaving its x and y location on the desk constant. Raising a mapped win- dow may generate exposure events for the window and any mapped subwindows that were formerly obscured. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, a ConfigureRequest event is generated, and no processing is performed. Otherwise, the window is raised. The error that can be generated by XRaiseWindow is BadWin- dow. Use XLowerWindow to lower a window so that it does not obscure any sibling windows. The definition for this func- tion is: XLowerWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. December 18, 1987 - 50 - w Specifies the window ID. The XLowerWindow function lowers the specified window to the bottom of the stack so that it does not obscure any sibling windows. If the windows are regarded as overlapping sheets of paper stacked on a desk, then lowering a window is analo- gous to moving the sheet to the bottom of the stack but leaving its x and y location on the desk constant. Lowering a mapped window will generate exposure events on any windows it formerly obscured. If the override_redirect attribute of the window is False and some other client has selected SubstructureRedirectMask on the parent, a ConfigureRequest event is generated, and no processing is performed. Otherwise, the window is lowered to the bottom of the stack. The error that can be generated by XLowerWindow is BadWin- dow. Use XCirculateSubwindows to circulate a subwindow up or down. The definition for this function is: XCirculateSubwindows(display, w, direction) Display *display; Window w; int direction; display Specifies the connection to the X server. w Specifies the window ID. direction Specifies the direction (up or down) that you want to circulate the window. You can pass one of these constants: RaiseLowest or LowerHighest. The XCirculateSubwindows function circulates the specified subwindow in the specified direction: RaiseLowest or LowerHighest. If some other client has selected Substruc- tureRedirectMask on the window, a CirculateRequest event is generated, and no further processing is performed. Other- wise, the processing described in the following paragraph is performed, and if the window is actually restacked, the X server generates a CirculateNotify event. If you specify RaiseLowest, this function raises the lowest mapped child (if any) that is occluded by another child to the top of the stack. If you specify LowerHighest, this function lowers the highest mapped child (if any) that occludes another child to the bottom of the stack. Exposure processing is performed on formerly obscured windows. December 18, 1987 - 51 - The errors that can be generated by XCirculateSubwindows are BadWindow and BadValue. Use XCirculateSubwindowsUp to raise the lowest mapped child of an occluded window. The definition for this function is: XCirculateSubwindowsUp(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XCirculateSubwindowsUp function raises the lowest mapped child of the specified window that is partially or com- pletely occluded by another child. Completely unobscured children are not affected. This is a convenience routine equivalent to XCirculateWindow (display, window, RaiseLowest). The error that can be generated by XCirculateSubwindowsUp is BadWindow. Use XCirculateSubwindowsDown to lower the highest mapped child of a window that partially or completely occludes another child. The definition for this function is: XCirculateSubwindowsDown(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XCirculateSubwindowsDown function lowers the highest mapped child of the specified window that partially or com- pletely occludes another child. Completely unobscured chil- dren are not affected. This is a convenience routine equivalent to XCirculateWindow (display, window, LowerHighest). The error that can be generated by XCirculateSubwindowsDown is BadWindow. Use XRestackWindows to restack a set of windows from top to bottom. The definition for this function is: December 18, 1987 - 52 - XRestackWindows(display, windows, nwindows); Display *display; Window windows[]; int nwindows; display Specifies the connection to the X server. windows Specifies an array containing the windows to be restacked. All the windows must have the same parent. nwindows Specifies the number of windows to be restacked. The XRestackWindows function restacks the windows in the order specified, from top to bottom. The stacking order of the first window in the windows array will be unaffected, but the other windows in the array will be stacked under- neath the first window in the order of the array. The stacking order of the other windows is not affected. If the override_redirect attribute of a window is False and some other client has selected SubstructureRedirectMask on the parent, ConfigureRequest events are generated for each window whose override_redirect is not set, and no further processing is performed. Otherwise, the windows will be restacked in top to bottom order. The error that can be generated by XRestackWindows is BadWindow. 3.9. Changing Window Attributes Xlib provides functions with which you can set window attri- butes. XChangeWindowAttributes is the more general function that allows you to set one or more window attributes pro- vided by the XSetWindowAttributes structure. See Section 3.2 for descriptions of these window attributes. The other functions described in this section allow you to set one specific window attribute, such as a window's background. Use XChangeWindowAttributes to change one or more window attributes. The definition for this function is: XChangeWindowAttributes(display, w, valuemask, attributes) Display *display; Window w; unsigned long valuemask; XSetWindowAttributes *attributes; display Specifies the connection to the X server. December 18, 1987 - 53 - w Specifies the window ID. valuemask Specifies which window attributes are defined in the attributes argument. This mask is the bitwise inclusive OR of the valid attribute mask bits. If valuemask is zero (0), the rest is ignored, and the attributes are not referenced. The values and restrictions are the same as for XCreateSimpleWin- dow and XCreateWindow. attributesAttributes of the window to be set at creation time should be set in this structure. The valuemask should have the appropriate bits set to indicate which attributes have been set in the structure. Depending on the valuemask, the XChangeWindowAttributes function uses the window attributes in the XSetWindowAttri- butes structure to change the specified window attributes. Changing the background does not cause the window contents to be changed. Use XClearWindow to repaint the window and its background. (See Section 6.2 for further information.) Setting the border or changing the background such that the border tile origin changes causes the border to be repainted. Changing the background of a root window to None or ParentRelative restores the default background pixmap. Changing the border of a root window to CopyFromParent restores the default border pixmap. Changing the win_gravity does not affect the current position of the win- dow. Either changing the backing_store of an obscured win- dow to WhenMapped or Always, or changing the backing_planes, backing_pixel, or save_under of a mapped window may have no immediate effect. Multiple clients can select input on the same window. If this is the case, their event masks are maintained separately. When an event is generated, it will be reported to all interested clients. However, at most, one client at a time can select for SubstructureRedirectMask, Resiz- eRedirectMask, and ButtonPressMask. If a client attempts to select any of these event masks and some other client has already selected it, the X server generates a BadAccess error. There is only one do_not_propagate_mask for a win- dow, not one per client. Changing the color map of a window (that is, defining a new map, not changing the contents of the existing map) gen- erates a ColormapNotify event. Changing the color map of a visible window may have no immediate effect on the screen because the map may not be installed. See XInstallColormap in Chapter 7. Changing the cursor of a root window to None restores the default cursor. Whenever possible, you are encouraged to share color maps. December 18, 1987 - 54 - The other event errors that can be generated by XChangeWin- dowAttributes are BadWindow, BadPixmap, BadColor, BadCursor, BadMatch, BadAccess, and BadValue. Use XSetWindowBackground to set the background of a speci- fied window to the specified pixel. The definition for this function is: XSetWindowBackground(display, w, background_pixel) Display *display; Window w; unsigned long background_pixel; display Specifies the connection to the X server. w Specifies the window ID. background_pixelSpecifies the pixel of the background. This pixel value determines which entry in the colormap is used. The XSetWindowBackground function sets the background pixel of the window to the pixel value you specify. Changing the background does not cause the window contents to be changed. XSetWindowBackground uses a pixmap of undefined size filled with the color associated with the pixel value you passed to the background_pixel argument. This can not be performed on an InputOnly window. An error will result if you try to change the background of an InputOnly window. The errors that can be generated by XSetWindowBackground are BadWindow and BadMatch. Use XSetWindowBackgroundPixmap to set the background of a specified window to the specified pixmap. The definition for XSetWindowBackgroundPixmap is: XSetWindowBackgroundPixmap(display, w, background_pixmap) Display *display; Window w; Pixmap background_pixmap; display Specifies the connection to the X server. w Specifies the window ID. December 18, 1987 - 55 - background_pixmapSpecifies the background pixmap. If a Pix- map ID is specified, the background is painted with this pixmap. If None, no background is painted. If ParentRelative, the parent's pixmap is used. The XSetWindowBackgroundPixmap function sets the background pixmap of the window to the pixmap you specify. If no back- ground Pixmap is specified, the background pixmap of the window's parent is used. On the root window, the default background will be restored. The background Pixmap can immediately be freed if no further explicit references to it are to be made. This can not be performed on an InputOnly window. An error will result if you try to change the back- ground of an InputOnly window. The errors that can be generated by XSetWindowBackgroundPix- map are BadWindow, BadPixmap, BadColor, and BadMatch. Note XSetWindowBackground and XSetWindowBackgroundPix- map do not change the current contents of the win- dow, and you may wish to clear and repaint the screen after these functions because they will not repaint the background you just set. Use XSetWindowBorder to change and repaint a window's border to the specified pixel. The definition for this function is: XSetWindowBorder(display, w, border_pixel) Display *display; Window w; unsigned long border_pixel; display Specifies the connection to the X server. w Specifies the window ID. border_pixelSpecifies the entry in the color map. The XSetWindowBorder function sets the border pixel of the window to the pixel value you specify. It uses this value as an entry into the color map to determine which color is to be used to paint the border. This can not be performed on an InputOnly window. It will cause an error to perform this on an InputOnly window. The errors that can be generated by XSetWindowBorder are BadWindow, BadPixmap, BadMatch, and BadValue. December 18, 1987 - 56 - Use XSetWindowBorderPixmap to change and repaint a window's border tile. The definition for this function is: XSetWindowBorderPixmap(display, w, border_pixmap) Display *display; Window w; Pixmap border_pixmap; display Specifies the connection to the X server. w Specifies the window ID. border_pixmapSpecifies the border pixmap. If you specify a pixmap ID, the associated pixmap is used for the border. If CopyFromParent is specified, a copy of the parent window's border pixmap is used. The XSetWindowBorderPixmap function sets the border pixmap of the window to the pixmap you specify. It uses this entry for the border. The border Pixmap can be freed immediately if no further explicit references to it are to be made. This can not be performed on an InputOnly window. It will cause an error to perform this on an InputOnly window. The errors that can be generated by XSetWindowBorderPixmap are BadWindow, BadPixmap, BadMatch, and BadValue. 3.10. Translating Window Coordinates Applications, mostly window managers, often need to perform a coordinate transformation from the coordinate space of one window to another window or need to determine which subwin- dow a coordinate lies in. XTranslateCoordinates fulfills these needs and avoids any race conditions by asking the X server to perform this operation. The definition for this function is: int XTranslateCoordinates(display, src_w, dest_w, src_x, src_y, dest_x_return, dest_y_return, child_return) Display *display; Window src_w, dest_w; int src_x, src_y; int *dest_x_return, *dest_y_return; Window *child_return; display Specifies the connection to the X server. src_w Specifies the window ID of the source window. dest_w Specifies the window ID of the destination window. December 18, 1987 - 57 - src_x src_y Specify the x and y coordinates within the source window. dest_x_return dest_y_returnReturns the x and y coordinates within the des- tination window. child_returnReturns the child if the coordinates are con- tained in a mapped child of the destination win- dow. The XTranslateCoordinates function takes the src_x and src_y coordinates within the source window relative to the source window's origin and returns these coordinates to dest_x_return and dest_y_return relative to the destination window's origin. If XTranslateCoordinates returns zero (0), src_w and dest_w are on different screens, and dest_x_return and dest_y_return are zero (0). If the coordinates are con- tained in a mapped child of dest_w, that child is returned to the child argument. The error that can be generated by XTranslateCoordinates is BadWindow. December 18, 1987 - 58 - Chapter 4 Window Information Functions Chapter 4 - Window Information Functions After you connect the display to the X server and create a window, you can use the Xlib window information functions to: o Obtain information about a window o Manipulate property lists o Obtain and change window properties o Manipulate window selection 4.1. Obtaining Window Information Xlib provides functions with which you can obtain informa- tion about the window tree, the current attributes of a win- dow, its current geometry, or the current pointer coordi- nates. Because they are most frequently used by window managers, these functions all return a status to indicate whether the window still exists. Use XQueryTree to obtain a list of children, the parent, and number of children for a specified window. The definition for this function is: Status XQueryTree(display, w, root_return, parent_return, children_return, nchildren_return) Display *display; Window w; Window *root_return; Window *parent_return; Window **children_return; unsigned int *nchildren_return; display Specifies the connection to the X server. w Specifies the window ID. For this window, you obtain the list of its children, its root, its parent, and the number of children. root_returnReturns the root window ID for the specified win- dow. December 18, 1987 - 59 - parent_returnReturns the parent window ID for the specified window. children_returnReturns a pointer to the list of children for the specified window. nchildren_returnReturns the number of children for the specified window. The XQueryTree function returns the root ID, the parent win- dow ID, a pointer to the list of children windows, and the number of children in the list for the specified window. Use XFree to free this list when it is no longer needed. (See Section 2.4 for further information.) The children are listed in current stacking order, from bottom-most (first) to top-most (last). XQueryTree returns zero (0) if it fails and nonzero if it succeeds. The error that can be generated by XQueryTree is BadWindow. Use XGetWindowAttributes to obtain the current attributes for a specified window. The definition for this function is: Status XGetWindowAttributes(display, w, window_attributes_return) Display *display; Window w; XWindowAttributes *window_attributes_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose current attributes you want to obtain. window_attributes_returnRturns the specified window's attri- butes in the XWindowAttributes structure. The XGetWindowAttributes function returns the current attri- butes for the specified window to an XWindowAttributes structure. This structure is defined as follows: December 18, 1987 - 60 - typedef struct { int x, y; /* location of window */ int width, height; /* width and height of window */ int border_width; /* border width of window */ int depth; /* depth of window */ Visual *visual; /* the associated visual structure */ Window root; /* root of screen containing window */ int class; /* InputOutput, InputOnly*/ int bit_gravity; /* one of bit gravity values */ int win_gravity; /* one of the window gravity values */ int backing_store; /* NotUseful, WhenMapped, Always */ unsigned long backing_planes;/* planes to be preserved if possible */ unsigned long backing_pixel;/* value to be used when restoring planes */ Bool save_under; /* boolean, should bits under be saved? */ Colormap colormap; /* color map to be associated with window */ Bool map_installed; /* boolean, is color map currently installed*/ int map_state; /* IsUnmapped, IsUnviewable, IsViewable */ long all_event_masks; /* set of events all people have interest in*/ long your_event_mask; /* my event mask */ long do_not_propagate_mask;/* set of events that should not propagate */ Bool override_redirect; /* boolean value for override-redirect */ Screen *screen; /* back pointer to correct screen */ } XWindowAttributes; The x and y members are set to the coordinates that define the location of the drawable. If the drawable is a window, these coordinates specify the upper left outer corner rela- tive to the parent window's origin. If the drawable is a pixmap, these members are set to zero (0). The width and height members are set to the drawable's dimensions. For a window, these dimensions specify the inside size of the win- dow, not including the border. The border_width member is set to the window's border width in pixels. If the drawable is a pixmap, this member is set to zero (0). The depth member is set to the depth of the pixmap (that is, bits per pixel for the object). The depth must be supported by the root of the specified drawable. The visual member is a pointer to the screen's associated Visual structure. The root member is set to the root ID of the screen containing the window. The class member is set to the window's class and can be one of the constants Inpu- tOutput or InputOnly. The bit_gravity member is set to the window's bit gravity and can be one of these constants: December 18, 1987 - 61 - ForgetGravity EastGravity NorthWestGravitySouthWestGravity NorthGravity SouthGravity NorthEastGravitySouthEastGravity WestGravity StaticGravity CenterGravity See the Configuring Windows section in Chapter 3 for addi- tional information on bit gravity. The win_gravity member is set to the window's window gravity and can be one of these constants: UnmapGravity EastGravity NorthWestGravitySouthWestGravity NorthGravity SouthGravity NorthEastGravitySouthEastGravity WestGravity StaticGravity CenterGravity The backing_store member is set to indicate how the X server should maintain the contents of a window. It can be set to one of the constants WhenMapped, Always, or NotUseful. The backing_planes member is set to indicate (with one bits) which bit planes of the window hold dynamic data that must be preserved in backing_stores and during save_unders. The backing_pixel member is set to indicate what values to use when restoring planes from a partial backing store. The save_under member is set to one of the constants True or False. The colormap member is set to the color map for the specified window and can be a colormap ID or the constant None. The map_installed member is set to indicate whether the color map is currently installed. It can be one of the constants True or False. The map_state member is set to indicate the state of the window and can be one of the con- stants IsUnmapped, IsUnviewable, or IsViewable. This member gets set to IsUnviewable if the window is mapped but some ancestor is unmapped. The all_event_masks member is set to the bitwise inclusive OR of all event masks selected on the window by interested clients. The your_event_mask member is set to the bitwise inclusive OR of all event masks selected by the querying client. The do_not_propagate_mask member is set to the bit- wise inclusive OR of the set of events that should not pro- pagate. See Section 8.3 for a discussion of events and the event mask. The override_redirect member is set to indicate whether this window overrides structure control facilities. It can be one of the constants True or False. Window manager clients December 18, 1987 - 62 - usually should ignore the window if this member is True. Transient windows should mark which windows they are associ- ated with. See Section 9.1.9 for further information. The screen member is set to a screen pointer that gives you a back pointer to the correct screen. This makes it easier to obtain the screen information without having to loop over the root window fields to see which matches. The error that can be generated by XGetWindowAttributes is BadWindow. Use XGetGeometry to obtain the current geometry of the specified drawable. The definition for this function is: Status XGetGeometry(display, d, root_return, x_return, y_return, width_return, height_return, border_width_return, depth_return) Display *display; Drawable d; Window *root_return; int *x_return, *y_return; unsigned int *width_return, *height_return; unsigned int *border_width_return; unsigned int *depth_return; display Specifies the connection to the X server. d Specifies the drawable. The drawable can be either a window or a pixmap. root_returnReturns the root window ID for the specified win- dow. x_return y_return Returns the x and y coordinates of the drawable. These coordinates define the location of the draw- able. For a window, these coordinates specify the upper left outer corner relative to its parent's origin. For pixmaps, these coordinates are always zero (0). width_return height_returnReturns the drawable's dimensions (width and height). For a window, these dimensions specify the inside size, not including the border. border_width_returnReturns the border width in pixels. The function returns the border width only if the drawable is a window. It returns zero (0) if the drawable is a pixmap. December 18, 1987 - 63 - depth_returnReturns the depth of the pixmap (bits per pixel for the object). The XGetGeometry function returns the root ID and the current geometry of the drawable. The geometry of the draw- able includes the x and y coordinates, width and height, border width, and depth. These are described in the argu- ment list. It is legal to pass to this function a window whose class is InputOnly. The error that can be generated by XGetGeometry is BadDraw- able. Use XQueryPointer to obtain the root window the pointer is currently on and the pointer coordinates relative to the root's origin. The definition for this function is: Bool XQueryPointer(display, w, root_return, child_return, root_x_return, root_y_return, win_x_return, win_y_return, mask_return) Display *display; Window w; Window *root_return, *child_return; int *root_x_return, *root_y_return; int *win_x_return, *win_y_return; unsigned int *mask_return; display Specifies the connection to the X server. w Specifies the window ID. root_returnReturns the root window ID for the specified win- dow. This root ID identifies the root window the pointer is currently on. child_returnReturns the child window ID that the pointer is located in, if any. root_x_return root_y_returnReturns the pointer coordinates relative to the root window's origin. win_x_return win_y_returnReturns the pointer coordinates relative to the specified window. mask_returnReturns the current state of the modifier keys and pointer buttons. The XQueryPointer function returns the root window the pointer is currently on and the pointer coordinates relative to the root window's origin. If XQueryPointer returns False, the pointer is not on the same screen as the window December 18, 1987 - 64 - associated with the window you passed to the w argument. In this case, the function returns the constant None to child_return and zero (0) to win_x_return and win_y_return. If XQueryPointer returns True, the pointer coordinates returned to win_x_return and win_y_return are relative to the origin of the window identified by the w argument. In this case, the function returns the ID of the child contain- ing the pointer, if any. The state of the keyboard buttons and the modifier keys are returned in the mask_return argument. Depending on the current state of the mouse buttons and the modifier keys, XQueryPointer can set this argument to the bitwise inclusive OR of one or more of the button or modifier key bitmasks: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. The error that can be generated by XQueryPointer is BadWin- dow. 4.2. Properties and Atoms A property is a collection of named typed data. The type of a property is defined by other properties, which allows for arbitrary extension in this type scheme. Data of more than one type may be associated with a single property. An Atom is just a nickname for a property, so that the protocol does not have to send arbitrary length property names back and forth. A property is also stored in one of several possible for- mats. The X server can store the information as 8-bit quan- tities, 16-bit quantities, or 32-bit quantities. This per- mits the X server to present the data in the byte order that the client expects. Note If you define further properties of complex type, you must encode and decode them yourself into one of the possible formats. The window system has a set of predefined properties (for example, the name of a window, size hints, and so on), and users can define any other arbitrary information and can associate them with windows. Each property has a name, which is an ISO Latin-1 string. For each named property there is a unique identifier (atom) associated with it. A property also has a type, for example, string or integer. These types are also indicated using atoms, so arbitrary new types can be defined. December 18, 1987 - 65 - Certain properties are predefined in the server for commonly used functions. The atoms for these properties are defined in <X11/Xatom.h>. To avoid name clashes with user symbols, the #define name for each atom has the ``XA_'' prefix added. See Section 4.3 for definitions of these properties. See Chapter 9 for an explanation of the functions that let you get and set much of the information stored in these prede- fined properties. You can use this mechanism to communicate other information between applications. The functions described in this sec- tion let you define new properties and get the unique Atom IDs in your applications. Atoms occur in five distinct name spaces within the proto- col. o Selections o Property names o Property types o Font properties o Type of a ClientMessage event (none are built into the X server) Any particular atom can have some client interpretation within each of the name spaces. The built-in selection properties, which name properties, are: PRIMARY SECONDARY The built-in property names are: CUT_BUFFER0 RGB_GREEN_MAP CUT_BUFFER1 RGB_RED_MAP CUT_BUFFER2 RESOURCE_MANAGER CUT_BUFFER3 WM_CLASS CUT_BUFFER4 WM_CLIENT_MACHINE CUT_BUFFER5 WM_COMMAND CUT_BUFFER6 WM_HINTS CUT_BUFFER7 WM_ICON_NAME RGB_BEST_MAP WM_ICON_SIZE RGB_BLUE_MAP WM_NAME RGB_DEFAULT_MAP WM_NORMAL_HINTS RGB_GRAY_MAP WM_ZOOM_HINTS December 18, 1987 - 66 - WM_TRANSIENT_FOR The built-in property types are: ARC POINT ATOM RGB_COLOR_MAP BITMAP RECTANGLE CARDINAL STRING COLORMAP VISUALID CURSOR WINDOW DRAWABLE WM_HINTS FONT WM_SIZE_HINTS INTEGER PIXMAP The built-in font property types are: MIN_SPACE STRIKEOUT_DESCENT NORM_SPACE STRIKEOUT_ASCENT MAX_SPACE ITALIC_ANGLE END_SPACE X_HEIGHT SUPERSCRIPT_X QUAD_WIDTH SUPERSCRIPT_Y WEIGHT SUBSCRIPT_X POINT_SIZE SUBSCRIPT_Y RESOLUTION UNDERLINE_POSITION COPYRIGHT UNDERLINE_THICKNESS NOTICE FONT_NAME FAMILY_NAME FULL_NAME CAP_HEIGHT Note See Chapter 6 for further information about font property atoms. Use XInternAtom to return an atom for a specified name. The definition for this function is: Atom XInternAtom(display, atom_name, only_if_exists) Display *display; char *atom_name; Bool only_if_exists; December 18, 1987 - 67 - display Specifies the connection to the X server. atom_name Specifies the name associated with the atom you want returned. only_if_existsSpecifies a boolean value that indicates whether XInternAtom creates the atom. You can pass one of the constants True or False. The XInternAtom function returns the atom identifier associ- ated with the string you passed to the atom_name argument. XInternAtom returns the atom for the specified atom_name if only_if_exists is True. If only_if_exists is False, the atom is created if it does not exist. Therefore, XInternA- tom can return None. You should use a null-terminated ISO Latin-1 string for atom_name. Case matters: the strings "thing", "Thing", and "thinG" all designate different atoms. The atom will remain defined even after the client who defined it has gone away. It will become undefined only when the last connection to the X server closes. The errors that can be generated by XInternAtom are BadAlloc and BadValue. Use XGetAtomName to return a name for the specified atom identifier. The definition for this function is: char *XGetAtomName(display, atom) Display *display; Atom atom; display Specifies the connection to the X server. atom Specifies the atom associated with the string name you want returned. The XGetAtomName function returns the name associated with the atom identifier you passed to the atom argument. You previously obtained the atom identifier by calling XInternA- tom. The error that can be generated by XGetAtomName is BadAtom. 4.3. Obtaining and Changing Window Properties Xlib provides functions with which you can obtain, rotate, or change a window property. In addition, Xlib provides other utility functions for predefined property operations. See Chapter 9 for further information about predefined pro- perty functions. December 18, 1987 - 68 - Use XGetWindowProperty to obtain the atom type and property format for a specified window. The definition for this func- tion is: int XGetWindowProperty(display, w, property, long_offset, long_length, delete, req_type, actual_type_return, actual_format_return, nitems_return, bytes_after_return, prop_return) Display *display; Window w; Atom property; long long_offset, long_length; Bool delete; Atom req_type; Atom *actual_type_return; int *actual_format_return; unsigned long *nitems_return; long *bytes_after_return; unsigned char **prop_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose atom type and property format you want to obtain. property Specifies the property atom. long_offsetSpecifies the offset in the specified property (in 32-bit quantities) where data will be retrieved. long_lengthSpecifies the length in 32-bit multiples of the data to be retrieved. delete Specifies a boolean value that determines whether the property is deleted from the window. You can pass one of these constants: True or False. req_type Specifies the atom identifier associated with the property type. You can pass an atom identifier or the constant AnyPropertyType. actual_type_returnReturns the atom identifier that defines the actual type of the property. actual_format_returnReturns the actual format of the pro- perty. nitems_returnReturns the actual number of 8-bit, 16-bit, or 32-bit items transferred. December 18, 1987 - 69 - bytes_after_returnReturns the number of bytes remaining. This is the number of bytes remaining to be read in the property if a partial read was performed. prop_returnReturns a pointer to the data, in the specified format. The XGetWindowProperty function returns the actual type of the property; the actual format of the property; the number of 8-bit, 16-bit, or 32-bit items transferred; the number of bytes remaining to be read in the property; and a pointer to the data actually returned. This function sets the return arguments according to the following: o If the specified property does not exist for the speci- fied window, XGetWindowProperty returns the constant None to the actual_type_return argument and the value zero (0) to the actual_format_return and bytes_after_return arguments. The nitems_return argu- ment is empty. In this case, the delete argument is ignored. o If the specified property exists, but its type does not match the specified type, XGetWindowProperty returns the actual property type to the actual_type_return argument; the actual property format (never zero) to the actual_format_return argument; and the property length in bytes (even if the actual_format_return is 16 or 32) to the bytes_after_return argument. It also ignores the delete argument. The nitems_return argu- ment is empty. o If the specified property exists, and either you assign the constant AnyPropertyType to the req_type argument or the specified type matches the actual property type, XGetWindowProperty returns the the actual property type to the actual_type_return argument and the actual pro- perty format (never zero) to the actual_format_return argument. It also returns a value to the bytes_after_return and nitems_return arguments, by defining the following values: N = actual length of the stored property in bytes (even if the format is 16 or 32) I = 4 * long_offset T = N - I L = MINIMUM(T, 4 * long_length) A = N - (I + L) The returned value starts at byte index I in the pro- perty (indexing from zero), and its length in bytes is L. A BadValue error is returned if the value for long_offset causes L to be negative. The value of bytes_after_return is A, giving the number of trailing December 18, 1987 - 70 - unread bytes in the stored property. If delete is True and bytes_after_return is zero (0) the function deletes the property from the window and generates a PropertyNotify event on the window. XGetWindowProperty allocates one extra byte and sets it to ASCII null, so that simple properties consisting of charac- ters do not have to be copied into yet another string before use. The function returns Success if it executes success- fully. The errors that can be generated by XGetWindowProperty are BadAtom, BadValue, and BadWindow. Use XListProperties to obtain a property list for a speci- fied window. The definition for this function is: Atom *XListProperties(display, w, num_prop_return) Display *display; Window w; int *num_prop_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose property list you want to obtain. num_prop_returnReturns the length of the properties array. The XListProperties function returns a pointer to an array of atom properties that are defined for the specified win- dow. Use XFree to free the memory allocated by this func- tion. (See Section 2.4 for further information.) The error that can be generated by XListProperties is BadWindow. Use XChangeProperty to change the property for a specified window. The definition for this function is: XChangeProperty(display, w, property, type, format, mode, data, nelements) Display *display; Window w; Atom property, type; int format; int mode; unsigned char *data; int nelements; December 18, 1987 - 71 - display Specifies the connection to the X server. w Specifies the window ID. This is the window whose property you want to change. property Specifies the property atom. The property remains defined even after the client who defined it goes away. The property becomes undefined if the application calls XDeleteProperty, if the applica- tion destroys the specified window, or if the application closes the last connection to the X server. type Specifies the type of the property. The X server does not interpret the type but simply passes it back to an application that later calls XGetPro- perty. format Specifies whether the data should be viewed as a list of 8-bit, 16-bit, or 32-bit quantities. This information allows the X server to correctly per- form byte-swap operations as necessary. If the format is 16-bit or 32-bit, you must explicitly cast your data pointer to a (char *) in the call to XChangeProperty. Possible values are 8, 16, and 32. mode Specifies the mode of the operation. You can pass one of these constants: PropModeReplace, PropMo- dePrepend, or PropModeAppend. data Specifies the property data. nelements Specifies the number of elements of the specified data format (8-bit, 16-bit, or 32-bit). The XChangeProperty function alters the property for the specified window and causes the X server to generate a Pro- pertyNotify event on that window. XChangeProperty does the following according to the value you assign to the mode argument: o If the mode argument is PropModeReplace, XChangePro- perty discards the previous property value. o If the mode argument is PropModePrepend or PropModeAp- pend, the type and format must match the existing pro- perty value. Otherwise, a BadMatch error is returned. If the property is undefined, it is treated as defined with the correct type and format with zero-length data. For PropModePrepend, the function inserts the data before the beginning of the existing data. For PropMo- deAppend, the function appends the data onto the end of December 18, 1987 - 72 - the existing data. The lifetime of a property is not tied to the storing client. Properties remain until explicitly deleted, or the window is destroyed, or until the server resets. See Sec- tion 2.5 for a discussion of what happens when the connec- tion to the X server is closed. The maximum size of a pro- perty is server dependent and may vary dynamically, depend- ing on the amount of memory the server has available. The other event errors that can be generated by XChangePro- perty are BadWindow, BadAtom, BadAlloc, and BadValue. Use XRotateWindowProperties to rotate properties in the pro- perties array. The definition for this function is: XRotateWindowProperties(display, w, properties, num_prop, npositions) Display *display; Window w; Atom properties[]; int num_prop; int npositions; display Specifies the connection to the X server. w Specifies the window ID. propertiesSpecifies the array of properties that are to be rotated. num_prop Specifies the length of the properties array. npositionsSpecifies the rotation amount. The XRotateWindowProperties function allows you to rotate properties in the properties array and causes the X server to generate a PropertyNotify event. If the property names in the properties array are viewed as being numbered start- ing from zero and if there are num_prop property names in the list, then the value associated with property name I becomes the value associated with property name (I + nposi- tions) mod N, for all I from zero to N - 1. The effect is to rotate the states by npositions places around the virtual ring of property names (right for positive npositions, left for negative npositions). If npositions mod N is nonzero, the X server generates a PropertyNotify event for each pro- perty in the order that they are listed in the array. If an atom occurs more than once in the list or no property with that name is defined for the window, a BadMatch error is generated. If a BadAtom or BadMatch error is generated, no properties are changed. December 18, 1987 - 73 - The other error that can be generated by XRotateWindowPro- perties is BadWindow. Use XDeleteProperty to delete a property for the specified window. The definition for this function is: XDeleteProperty(display, w, property) Display *display; Window w; Atom property; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose property you want to delete. property Specifies the property atom. The XDeleteProperty function deletes the specified property only if the property was defined on the specified window. XDeleteProperty causes the X server to generate a Proper- tyNotify event on the window, unless the property does not exist. The errors that can be generated by XDeleteProperty are BadWindow and BadAtom. 4.4. Manipulating Window Selection A selection can be thought of as an indirect property with a dynamic type. That is, rather than having the property stored in the X server, the property is maintained by some client (the owner). A selection is global in nature, being thought of as belonging to the user but maintained by clients, rather than being private to a particular window subhierarchy or a particular set of clients. When a client asks for the contents of a selection, it specifies a selec- tion target type. This target type can be used to control the transmitted representation of the contents. For exam- ple, if the selection is ``the last thing the user clicked on,'' and that is currently an image, then the target type might specify whether the contents of the image should be sent in XYFormat or ZFormat. The target type can also be used to control the class of contents transmitted, for example, asking for the ``looks'' (fonts, line spacing, indentation, and so forth) of a para- graph selection, not the text of the paragraph. The target type can also be used for other purposes. The semantics are not constrained by the protocol. Xlib provides functions with which you can set, get, or December 18, 1987 - 74 - convert window selection. This allows applications to implement the notion of current selection, which requires notification be sent to applications when they no longer own the selection. Applications that support selection often highlight the current selection and need to be able to be informed when some other application has acquired the selec- tion in order to be able to unhighlight the selection. Use XSetSelectionOwner to set the selection owner. The definition for this function is: XSetSelectionOwner(display, selection, owner, time) Display *display; Atom selection; Window owner; Time time; display Specifies the connection to the X server. selection Specifies the selection atom. owner Specifies the owner of the specified selection atom. You can pass a window ID or the constant None. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XSetSelectionOwner function changes the owner and last change time for the specified selection. The function has no effect if the value you pass to the time argument is ear- lier than the current last-change time of the specified selection or is later than the current X server time. Oth- erwise, the last-change time is set to the specified time, with CurrentTime replaced by the current server time. If the owner window is specified as None, then the owner of the selection becomes None (that is, no owner). Otherwise the owner of the selection becomes the client executing the request. If the new owner (whether a client or None) is not the same as the current owner of the selection, and the current owner is not None, the current owner is sent a SelectionClear event. If the client that is the owner of a selection is later terminated (that is, its connection is closed) or if the owner window it has specified in the request is later destroyed, the owner of the selection automatically reverts to None, but the last-change time is not affected. The selection atom is uninterpreted by the X server. The owner window is returned by the XGetSelectionOwner function and is reported in SelectionRequest and SelectionClear events. December 18, 1987 - 75 - Selections are global to the X server. The errors that can be generated by XSetSelectionOwner are BadWindow and BadAtom. Use XGetSelectionOwner to return selection owner. The definition for this function is: Window XGetSelectionOwner(display, selection) Display *display; Atom selection; display Specifies the connection to the X server. selection Specifies the selection atom. This is the atom whose owner you want returned. The XGetSelectionOwner function returns the window ID asso- ciated with the window that currently owns the specified selection. If no selection was specified, the function returns the constant None. If None is returned, there is no owner for the selection. The error that can be generated by XGetSelectionOwner is BadAtom. Use XConvertSelection to request a selection conversion. The definition for this function is: XConvertSelection(display, selection, target, property, requestor, time) Display *display; Atom selection, target; Atom property; Window requestor; Time time; display Specifies the connection to the X server. selection Specifies the selection atom. target Specifies the target atom. property Specifies the property atom. You also can pass the constant None. requestor Specifies the requestor. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. December 18, 1987 - 76 - XConvertSelection requests that the specified selection be converted to the specified target type: o If the specified selection has an owner, the X server sends a SelectionRequest event to that owner. o If no owner for the specified selection exists, the X server generates a SelectionNotify event to the reques- tor with property None. The arguments are passed on unchanged in either event. There are two predefined selection atoms: ``PRIMARY'' and ``SECONDARY''. See Chapter 8 for more information on events, and in particular the SelectionNotify event. The errors that can be generated by XConvertSelection are BadWindow and BadAtom. December 18, 1987 - 77 - Chapter 5 Graphics Resource Functions Chapter 5 - Graphics Resource Functions After you connect your program to the X server by calling XOpenDisplay, you can use the Xlib graphics resource functions to: o Manipulate the color map o Manipulate pixmaps o Manipulate graphics context/state o Use GC convenience routines There are a number of resources used when performing graph- ics operations in X. Most information about performing graphics (for example, foreground color, background color, line style, and so on) are stored in resources called graph- ics contexts. Most graphics operations (see chapter 6) take a graphics context or ``GC'' as an argument. While it, in theory, is possible to share GCs between applications, it is expected that applications will use their own GCs when per- forming operations, and such use is highly discouraged because the library may cache GC state. Windows in X always have an associated color map that pro- vides a level of indirection between pixel values and color displayed on the screen. Many of the hardware displays built today have a single color map, so the primitives are written to encourage sharing of color map entries between applications. Because color maps are associated with win- dows, X will support displays with multiple color maps and, indeed, different types of color maps. If there are not sufficient color map resources in the display, some windows may not be displayed in their true colors. A window manager can set which windows are displayed in their true colors if more than one color map is required for the color resources the applications are using. Off screen memory or pixmaps are often used to define fre- quently used images for later use in graphics operations. Pixmaps are also used to define tiles or patterns for use as window backgrounds, borders, or cursors. A single bit plane pixmap is sometimes referred to as a bitmap. There may not be an unlimited amount of off screen memory, so it should be regarded as a precious resource. Graphics operations can be performed to either windows or December 18, 1987 - 78 - pixmaps, also called drawables, in the discussion below and in the next chapter. Each drawable exists on a single screen or root and can only be used on that root. GCs can also only be used with drawables of matching roots and depths. 5.1. Manipulating the Color Map Xlib provides functions with which you can manipulate a color map. This section discusses how to: o Create, copy, and destroy the color map o Allocate and deallocate colors 5.1.1. Creating, Copying, and Destroying Color Maps Xlib provides functions with which you can create, copy, free, or set a color map. Color Map Manipulation The following functions manipulate the representation of color on the screen. For each possible value a pixel may take on a display, there is a color cell in the color map. For example, if a display is 4 bits deep, pixel values 0 through 15 are defined. A color map is the collection of the color cells. A color cell consists of a triple of red, green, and blue. As each pixel is read out of display memory, its value is taken and looked up in the color map. The values of the cell determine what color is displayed on the screen. On a multiplane display with a black and white monitor (grayscale, but not color), these values may or may not be combined to determine the brightness on the screen. Screens always have a color map. Programs will typically allocate cells out of a common map. It is highly discouraged to write applications which monopolize color resources. On a screen that either cannot load the color map or cannot have a fully independent color map, only cer- tain kinds of allocations may work. One or more (on certain hardware) color maps may be resident at one time. The XIn- stallColormap function (see Chapter 7) is used to install a color map. The DefaultVisual macro returns the default visual type for the specified screen. Color maps are local to a particular screen. The DefaultColormap macro returns the type of color map. Possible types are represented by these constants: StaticGray, GrayScale, StaticColor, Pseu- doColor, TrueColor, or DirectColor. These types are more fully discussed in the section on visual types in Chapter 3. Note The introduction of color changes the view a pro- grammer should take when dealing with a bitmap display. For example, when printing text, you December 18, 1987 - 79 - write in a color (pixel value) rather than setting or clearing bits. Hardware will impose limits (number of significant bits, for example) on these values. Typically, one allocates particular pixel values or sets of values. If read only, the pixel values may be shared among multiple applications. If read/write, they are exclusively owned by the program, and the color cell associated with the pixel value may be changed at will. The functions in this section operate on an XColor struc- ture: typedef struct { unsigned long pixel;/* pixel value */ unsigned short red, green, blue;/* rgb values */ char flags; /* DoRed, DoGreen, DoBlue */ char pad; } XColor; The red, green and blue values are scaled between 0 and 65535. That is, on full in a color is a value of 65535 independent of the number of bit planes of the display. Half brightness in a color would be a value of 32767 and off would be 0. This representation gives uniform results for color values across displays with different number of bit planes. The flags member, which can be one or more of DoRed, DoGreen, and DoBlue, is used in some functions to control which members will be set. Use XCreateColormap to create a color map for the screen on which the window resides and to return the Colormap ID. The definition for this function is: Colormap XCreateColormap(display, w, visual, alloc) Display *display; Window w; Visual *visual; int alloc; display Specifies the connection to the X server. w Specifies the window ID. This is the window on whose screen you want to create a color map. visual Specifies a pointer to a visual type supported on the screen. If the visual type is not one sup- ported by the screen, the function returns a December 18, 1987 - 80 - BadMatch error. alloc Specifies the color map entries to be allocated. You can pass one of these constants: AllocNone or AllocAll. The XCreateColormap function creates a color map of the specified visual type for the screen on which the window resides and associates the Colormap ID with it. XCreateColormap operates on a Visual structure, whose members contain information about the color mapping that is possible. The members of this structure pertinent to the discussion of XCreateColormap are class, red_mask, green_mask, blue_mask, and map_entries. The class member specifies the screen class and can be one of these constants: GrayScale, Pseu- doColor, DirectColor, StaticColor, StaticGray, or TrueColor. The red_mask, green_mask, and blue_mask members specify the color mask values. The map_entries member specifies the color map entries. The class member constant determines whether the initial values for map_entries are defined. If the class member is GrayScale, PseudoColor, or DirectColor, the initial values for map_entries are undefined. However, if the class member is StaticColor, StaticGray, or TrueColor, map_entries has initial values that are defined. These values are specific to the visual type and are not defined by the X server. The class member constant also determines the constant you should pass to the alloc argument: o If the class member is StaticGray, StaticColor, or TrueColor you must pass AllocNone. Otherwise, the function returns a BadMatch error. o If the class member is any other class, you can pass AllocNone. In this case, the color map has no values defined for map_entries. This allows your client pro- grams to allocate the entries in the color map. You can also pass AllocAll. In this case, XCreateColormap allocates the entire color map as writable. The ini- tial values of all map_entries are undefined. You can- not free any of these map_entries with a call to the function XFreeColors. For a color map class of GrayScale or PseudoColor, the processing simulates a call to the function XAlloc- Color, where XAllocColor returns all pixel values from zero to N - 1. The value N represents the map_entries value in the specified Visual structure. For a color map class of DirectColor, the processing simulates a call to the function XAllocColorPlanes, where XAlloc- ColorPlanes returns a pixel value of zero and rmask, December 18, 1987 - 81 - gmask, and bmask values containing the same bits as the red_mask, green_mask, and blue_mask members in the specified Visual structure. The other event errors that can be generated by XCreateColormap are BadWindow, BadAlloc, BadMatch, and Bad- Value. Use XCopyColormapAndFree to obtain a new color map when allocating out of a previously shared color map has failed due to resource exhaustion. That is, too many cells or planes were in use in the original color map. The defini- tion for this function is: Colormap XCopyColormapAndFree(display, cmap) Display *display; Colormap cmap; display Specifies the connection to the X server. cmap Specifies the color map ID. XCopyColormapAndFree: o Creates a colormap of the same visual type and for the same screen as the cmap argument and returns the new colormap ID. o Moves all of the client's existing allocation from cmap to the new colormap with their color values intact and their read-only or writable characteristics intact and frees those entries. Color values in other entries in the new colormap are undefined. o If cmap was created by the client with the alloc argu- ment set to AllocAll, the new colormap is also created with AllocAll all color values for all entries are copied from cmap, and then all entries in cmap are freed. o If cmap was not created by those clients with AllocAll, the allocations to be moved are all those pixels and planes that have been allocated by the client using XAllocColor, XAllocNamedColor, XAllocColorCells, or XAllocColorPlanes and which have not been freed since they were allocated. The errors that can be generated by XCopyColormapAndFree are BadAlloc and BadColor. December 18, 1987 - 82 - Use XFreeColormap to delete the association between the Colormap resource ID and the color map. The definition for this function is: XFreeColormap(display, cmap) Display *display; Colormap cmap; display Specifies the connection to the X server. cmap Specifies the color map ID. This is the color map associated with the resource ID you want to delete. The XFreeColormap function deletes the association between the colormap resource ID and the color map. However, this function has no effect on a default color map for a screen. If cmap is an installed map for a screen it is uninstalled. See XUninstallColormap. If cmap is defined as the color map for a window (by XCreateWindow or XChangeWindowAttributes) XFreeColormap changes the color map associated with the win- dow to None and generates a ColormapNotify event. The colors displayed for a window with a colormap of None are not defined by X. The error that can be generated by XFreeColormap is Bad- Color. Use XSetWindowColormap to set the color map for a specified window. The definition for this function is: XSetWindowColormap(display, w, cmap) Display *display; Window w; Colormap cmap; display Specifies the connection to the X server. w Specifies the window ID. This is the window to which you want to set the color map. cmap Specifies the color map ID. The XSetWindowColormap function sets the specified color map of the specified window. The errors that can be generated by XSetWindowColormap are BadWindow, BadColor, and BadMatch. December 18, 1987 - 83 - 5.1.2. Allocating and Freeing Colors Xlib provides functions with which you can allocate or deal- locate colors. There are two ways of allocating color cells: explicitly as read only entries by pixel value or read/write, where you can allocate N colors and planes simultaneously. The read/write cells you allocate do not have defined colors until set with XStoreColors. To determine the color names, the X server uses a color data base. On a UNIX-based system, this data base is /usr/lib/rgb, and a printable copy of it is stored in /usr/lib/rgb.txt. The name and contents of this file are operating system specific. Use XAllocColor to obtain the closest color provided by the hardware. The definition for this function is: Status XAllocColor(display, cmap, screen_def_return) Display *display; Colormap cmap; XColor *screen_def_return; display Specifies the connection to the X server. cmap Specifies the color map ID. screen_def_returnReturns the values actually used in the color map. The XAllocColor function returns the pixel value indicating the closest color supported by the hardware. It also returns the red, green, and blue values actually used. XAl- locColor allocates a read-only color map entry corresponding to the closest red, green, and blue values supported by the hardware. The corresponding color map cell is read-only. In addition, XAllocColor returns zero (0) if there were some problem (typically lack of resources) or nonzero if it suc- ceeded. Read-only color map cells are shared among clients. When the last client deallocates a shared cell, it is deal- located. The errors that can be generated by XAllocColor are BadAlloc and BadColor. Use XAllocNamedColor to obtain the color definition struc- ture for a specified color and the closest color supported by the hardware. The definition for this function is: December 18, 1987 - 84 - Status XAllocNamedColor(display, cmap, colorname, screen_def_return, exact_def_return) Display *display; Colormap cmap; char *colorname; XColor *screen_def_return, *exact_def_return; display Specifies the connection to the X server. cmap Specifies the color map ID. colorname Specifies the color name string (for example, "red") whose color definition structure you want returned. You should use the ISO Latin-1 encod- ing, and upper/lower case does not matter. screen_def_returnReturns the values actually used in the color map. exact_def_returnReturns the true pixel values that indicate the closest color provided by the hardware for the specified color name. The XAllocNamedColor function determines the correct color (shade) for the given screen. XAllocNamedColor returns zero (0) when it encounters an error or a nonzero when it succeeds. Both the exact data base definition and the closest color supported by the hardware are returned. The errors that can be generated by XAllocNamedColor are BadColor, BadAlloc, and BadName. Use XLookupColor to look up the name of a color. The defin- ition for this function is: Status XLookupColor(display, cmap, colorname, screen_def_return, exact_def_return) Display *display; Colormap cmap; char *colorname; XColor *screen_def_return, *exact_def_return; display Specifies the connection to the X server. cmap Specifies the color map ID. colorname Specifies the color name string (for example, "red") whose color definition structure you want returned. You should use the ISO Latin-1 encod- ing, and upper/lower case does not matter. December 18, 1987 - 85 - screen_def_returnReturns the values actually used in the color map. exact_def_returnReturns the true pixel values that indicate the closest color provided by the hardware for the specified color name. The XLookupColor function looks up the string name of a color with respect to the screen associated with the speci- fied cmap and returns both the exact color values and the closest values provided by the hardware with respect to the visual type of cmap. You should use the ISO Latin-1 encod- ing for the name, and upper/lower case does not matter. In addition, XLookupColor returns nonzero if the spec existed in the RGB data base or zero (0) if it did not exist. The errors that can be generated by XLookupColor are Bad- Color and BadName. Use XStoreColors to set the colors of the specified pixel values to the closest available hardware colors. The defin- ition for this function is: XStoreColors(display, cmap, defs, ncolors) Display *display; Colormap cmap; XColor defs[]; int ncolors; display Specifies the connection to the X server. cmap Specifies the color map ID. defs Specifies an array of color definition structures. ncolors Specifies the number of XColor structures in the color definition array. The XStoreColors function changes the color map entries of the pixel values specified in the pixel members of the XColor structures. You specify which color components to be changed by passing the constants DoRed, DoGreen, and/or DoB- lue to the flags members of the XColor structures. If the colormap is an installed map for its screen, the changes are visible immediately. XStoreColors changes the specified pixels if they are allocated writable in cmap by any client, even if one or more pixels generates an error. A BadValue error is generated if a specified pixel is not a valid index into cmap and a BadAccess error is generated if a specified pixel either is unallocated or is allocated read-only. If more than one pixel is in error, which one is reported is arbitrary. December 18, 1987 - 86 - The other event errors that can be generated by XStoreColors are BadAccess and BadColor. Use XStoreColor to set the color of the specified pixel value to the closest available hardware color. The defini- tion for this function is: XStoreColor(display, cmap, screen_def_return) Display *display; Colormap cmap; XColor *screen_def_return; display Specifies the connection to the X server. cmap Specifies the color map ID. screen_def_returnReturns the values actually used in the color map. The XStoreColor function changes the color map entry of the pixel value specified in the pixel member of the XColor structure. XStoreColor changes the: o Color map entry of the pixel value. You specified this value in the pixel member of the XColor structure. This pixel value must be a read/write cell and a valid index into cmap. A BadValue error is generated if a specified pixel is not a valid index into cmap. o Red, green, and/or blue color components. You specify which color components to be changed by passing the constants DoRed, DoGreen, and/or DoBlue to the flags member of the XColor structure. If the color map is an installed map for its screen, the changes are visible immediately. o Specified pixel if it is allocated writable in cmap by any client, even if the pixel generates an error. The other error that can be generated by XStoreColor is Bad- Color. Use XAllocColorCells to allocate color cells. The definition for this function is: December 18, 1987 - 87 - Status XAllocColorCells(display, cmap, contig, plane_masks_return, nplanes, pixels_return, ncolors) Display *display; Colormap cmap; Bool contig; unsigned long plane_masks_return[]; unsigned int nplanes; unsigned long pixels_return[]; unsigned int ncolors; display Specifies the connection to the X server. cmap Specifies the color map ID. contig Specifies a boolean value. You pass the value 1 if the planes must be contiguous or the value 0 if the planes do not need to be contiguous. plane_mask_returnReturns an array of plane masks. nplanes Specifies the number of plane masks that are to be returned in the plane masks array. pixels_returnReturns an array of pixel values. ncolors Specifies the number of pixel values that are to be returned in the pixels_return array. The XAllocColorCells function allocates color cells. The number of colors must be positive and the number of planes nonnegative. Otherwise, a BadValue error is generated. If ncolors and nplanes are requested, then ncolors pixels and nplane plane masks are returned. No mask will have any bits in common with any other mask or with any of the pixels. By ORing together masks and pixels, ncolors* 2nplanes distinct pixels can be produced. All of these are allocated writable by the request. For GrayScale or PseudoColor, each mask will have exactly one bit, and, for DirectColor, each will have exactly three bits. If contigs is True, and if all masks are ORed together, a single contiguous set of bits will be formed for GrayScale or PseudoColor and three con- tiguous sets of bits (one within each pixel subfield) for DirectColor. The RGB values of the allocated entries are undefined. The other event errors that can be generated by XAllocColor- Cells are BadColor, BadValue, and BadAlloc. Use XAllocColorPlanes to allocate color planes. The defini- tion for this function is: December 18, 1987 - 88 - Status XAllocColorPlanes(display, cmap, contig, pixels_return, ncolors, nreds, ngreens, nblues, rmask_return, gmask_return, bmask_return) Display *display; Colormap cmap; Bool contig; unsigned long pixels_return[]; int ncolors; int nreds, ngreens, nblues; unsigned long *rmask_return, *gmask_return, *bmask_return; display Specifies the connection to the X server. cmap Specifies the color map ID. contig Specifies a boolean value. You pass the value 1 if the planes must be contiguous or the value 0 if the planes do not need to be contiguous. pixels_returnReturns an array of pixel values. XAllocColor- Planes returns the pixel values in this array. ncolors Specifies the number of pixel values that are to be returned in the pixels_return array. nreds ngreens nblues Specify the number of red, green, and blue colors (shades). The value you pass must be non- negative. rmask_return gmask_return bmask_returnReturn bit masks for the red, green, and blue planes. The XAllocColorPlanes function allocates color planes. The specified ncolors must be positive, and nreds, ngreens, and nblues must be nonnegative. Otherwise, a BadValue error is generated. If ncolors colors, nreds reds, ngreens greens, and nblues blues are requested, ncolors pixels are returned, and the masks have nreds, ngreens, and nblues bits set respectively. If contiguous is True, each mask will have a contiguous set of bits. No mask will have any bits in com- mon with any other mask or with any of the pixels. For DirectColor, each mask will lie within the corresponding pixel subfield. By ORing together subsets of masks with pixels, ncolors*2(nreds+ngreens+nblues) distinct pixels can be produced. All of these are allocated by the request. However, in the colormap, there are only ncolors*2nreds independent red entries, ncolors*2ngreens independent green entries, and ncolors*2nblues independent blue entries. This is true even for PseudoColor. When the colormap entry for a December 18, 1987 - 89 - pixel value is changed (using XStoreColors or XStoreNamedColor), the pixel is decomposed according to the masks, and the corresponding independent entries are updated. The other event errors that can be generated by XAllocColor- Planes are BadAlloc, BadValue, and BadColor. Use XStoreNamedColor to allocate a color cell by name. The definition for this function is: XStoreNamedColor(display, cmap, color, pixel, flags) Display *display; Colormap cmap; char *color; unsigned long pixel; int flags; display Specifies the connection to the X server. cmap Specifies the color map ID. color Specifies the color name string (for example, ``red''). The function then allocates this color cell. You should use the ISO Latin-1 encoding, and upper/lower case does not matter. pixel Specifies the entry in the color map. flags Specifies which red, green, and blue indexes are set. The XStoreNamedColor function looks up the named color with respect to the screen associated with cmap and stores the result in cmap. The pixel argument determines the entry in the color map. The flags argument determines which of the red, green, and blue indexes are set. You can set this member to the bitwise inclusive OR of the bits from the con- stant set DoRed, DoGreen, and DoBlue. A BadValue error is generated if a specified pixel is not a valid index into cmap and a BadAccess error is generated if a specified pixel either is unallocated or is allocated read-only. If more than one pixel is in error, which one is reported is arbi- trary. The errors that can be generated by XStoreNamedColor are BadColor, BadAccess, BadName, and BadValue. Use XFreeColors to free color map cells. The definition for this function is: December 18, 1987 - 90 - XFreeColors(display, cmap, pixels, npixels, planes) Display *display; Colormap cmap; unsigned long pixels[]; int npixels; unsigned long planes; display Specifies the connection to the X server. cmap Specifies the color map ID. pixels Specifies an array of pixel values. These pixel values map to the cells in the specified color map. npixels Specifies the number of pixels. planes Specifies the planes you want to free. The XFreeColors function frees the cells represented by pix- els whose values are in the pixels array. The planes argu- ment should not have any bits in common with any of the pix- els. The set of all pixels is produced by ORing together subsets of the planes argument with the pixels. The request frees all of these pixels that were allocated by the client (using XAllocColor, XAllocNamedColor, XAllocColorCells, and XAllocColorPlanes). Note that freeing an individual pixel obtained from XAllocColorPlanes may not actually allow it to be reused until all of its related pixels are also freed. All specified pixels that are allocated by the client in cmap are freed, even if one or more pixels produce an error. A BadValue error is generated if a specified pixel is not a valid index into cmap. A BadAccess error is generated if a specified pixel is not allocated by the client (that is, is unallocated or is only allocated by another client). If more than one pixel is in error, the one reported is arbi- trary. The errors that can be generated by XFreeColors are Bad- Color, BadAccess, and BadValue. 5.1.3. Reading Entries in a Colormap The XQueryColor function returns the red, green, and blue color values stored in cmap for the pixel value you passed to the pixel member of the XColor structure. The values returned for an unallocated entry are undefined. The XQueryColors function does the same thing, except that it operates on an array of XColor structures. They also set the flags member in the XColor structure to all three colors. A BadValue error is generated if a pixel is not a valid index into cmap. If more than one pixel is in error, December 18, 1987 - 91 - which one is reported is arbitrary. Use XQueryColor to obtain the color values for a single specified pixel value. The definition for this function is: XQueryColor(display, cmap, def_return) Display *display; Colormap cmap; XColor *def_return; display Specifies the connection to the X server. cmap Specifies the color map ID. def_returnReturns the RGB values for the pixel specified in the structure. The other event errors that can be generated by XQueryColor are BadValue and BadColor. Use XQueryColors to obtain color values for an array of pix- els stored in color structures. The definition for this function is: XQueryColors(display, cmap, defs_return, ncolors) Display *display; Colormap cmap; XColor defs_return[]; int ncolors; display Specifies the connection to the X server. cmap Specifies the color map ID. defs_returnReturns an array of color definition structures. ncolors Specifies the number of XColor structures in the color definition array. The other event errors that can be generated by XQueryColors are BadValue and BadColor. 5.2. Manipulating Pixmaps Xlib provides functions with which you can create or free a pixmap. A few programs may want to manipulate pixels that they later display on the screen. This section describes functions that will move pixels from the program to the win- dow system, or from the window system to the program. You must be careful to adhere to the data representation December 18, 1987 - 92 - described at the beginning of this document to keep programs portable between machine architectures. Pixmaps can only be used on the screen on which they were created. Pixmaps are off-screen resources that are used for a number of operations. A bitmap is a single bit pixmap. These include defining cursors or temporarily saving some part of the screen for later, either as tiling patterns or as the source for certain raster operations. Use XCreatePixmap to create a pixmap of a specified size. The definition for this function is: Pixmap XCreatePixmap(display, d, width, height, depth) Display *display; Drawable d; unsigned int width, height; unsigned int depth; display Specifies the connection to the X server. d Specifies which screen the pixmap is created on. width height Specify the width and height. These dimensions define the width and height of the pixmap. The values you pass must be nonzero. depth Specifies the depth of the pixmap. The depth must be supported by the root of the specified draw- able. The XCreatePixmap function creates a pixmap of the width, height, and depth you specified. It also assigns the pixmap ID to it. It is valid to pass a window whose class is Inpu- tOnly to the drawable argument. The width and height argu- ments must be nonzero. Otherwise, a BadValue error is gen- erated. The depth argument must be one of the depths sup- ported by the root of the specified drawable. Otherwise, a BadValue error is generated. The server uses the drawable argument to determine which screen the pixmap is stored on. The pixmap can only be used on this screen and only with other drawables windows of the same depth. (See XCopyPlane for an exception to this rule). The initial contents of the pixmap are undefined. If this routine returns zero (0), there was insufficient space for the pixmap. The errors that can be generated by XCreatePixmap are BadAl- loc, BadDrawable, and BadValue. December 18, 1987 - 93 - Use XFreePixmap to free all storage associated with a speci- fied pixmap. The definition for this function is: XFreePixmap(display, pixmap) Display *display; Pixmap pixmap; display Specifies the connection to the X server. pixmap Specifies the pixmap. The XFreePixmap function first deletes the association between the pixmap ID and the pixmap. Then, the X server frees the pixmap storage when no other resources reference it. The pixmap should never be referenced again. The error that can be generated by XFreePixmap is BadPixmap. 5.3. Manipulating Graphics Context/State Most attributes of graphics operations are stored in Graphic Contexts or GCs. These include line width, line style, plane mask, foreground, background, tile, stipple, clipping region, end style, join style, and so on. Graphics opera- tions (for example, drawing lines) use these values to determine the actual drawing operation. Extensions to X may add additional components to GCs. Xlib provides calls for changing the state of GCs. Xlib implements a write-back cache for all elements of a GC that are not resource IDs to allow it to implement the tran- sparent coalescing changes to GCs. GCs are neither expected nor encouraged to be shared between client applications, so this write-back caching should present no problems. Appli- cations cannot share GCs without external synchronization. Therefore, sharing GCs between applications is highly discouraged. Graphic Operations You use display functions when you update a section of the screen (destination) with bits from somewhere else (source). Many GC functions take one of these display functions as an argument. The function defines how the new destination bits are to be computed from the source bits and the old destina- tion bits. GXcopy is typically the most useful because it will work on a color display, but special applications may use other functions, particularly in concert with particular planes of a color display. The 16 such functions, defined in <X11/X.h>, are: ___________________________________________________ Function Name Hex Code Operation ___________________________________________________ GXclear 0x0 0 December 18, 1987 - 94 - ___________________________________________________ Function Name Hex Code Operation ___________________________________________________ GXand 0x1 src AND dst GXandReverse 0x2 src AND NOT dst GXcopy 0x3 src GXandInverted 0x4 (NOT src) AND dst GXnoop 0x5 dst GXxor 0x6 src XOR dst GXor 0x7 src OR dst GXnor 0x8 (NOT src) AND (NOT dst) GXequiv 0x9 (NOT src) XOR dst GXinvert 0xa NOT dst GXorReverse 0xb src OR (NOT dst) GXcopyInverted 0xc NOT src GXorInverted 0xd (NOT src) OR dst GXnand 0xe (NOT src) OR (NOT dst) GXset 0xf 1 ___________________________________________________ Many of the color functions below take either pixel values or planes as an argument. The planes argument is of type long and it specifies which planes of the display are to be modified, one bit per plane. A monochrome display has only one plane and will be the least significant bit of the word. As planes are added to the display hardware, they will occupy more significant bits in the plane mask. A macro constant AllPlanes can be used to refer to all planes of a display simultaneously (~0). Most operations use an object called a GC, which is short for Graphics Con- text. The contents of the GC object are private to the library. Several procedures take structures of type GCValues. The following lists each entry by its defined value, not by its position in the XGCValues structure: December 18, 1987 - 95 - #define GCFunction (1L<<0) #define GCPlaneMask (1L<<1) #define GCForeground (1L<<2) #define GCBackground (1L<<3) #define GCLineWidth (1L<<4) #define GCLineStyle (1L<<5) #define GCCapStyle (1L<<6) #define GCJoinStyle (1L<<7) #define GCFillStyle (1L<<8) #define GCFillRule (1L<<9) #define GCTile (1L<<10) #define GCStipple (1L<<11) #define GCTileStipXOrigin (1L<<12) #define GCTileStipYOrigin (1L<<13) #define GCFont (1L<<14) #define GCSubwindowMode (1L<<15) #define GCGraphicsExposures (1L<<16) #define GCClipXOrigin (1L<<17) #define GCClipYOrigin (1L<<18) #define GCClipMask (1L<<19) #define GCDashOffset (1L<<20) #define GCDashList (1L<<21) #define GCArcMode (1L<<22) typedef struct { int function; /* logical operation */ unsigned long plane_mask;/* plane mask */ unsigned long foreground;/* foreground pixel */ unsigned long background;/* background pixel */ int line_width; /* line width (in pixels) */ int line_style; /* LineSolid, LineOnOffDash, LineDoubleDash */ int cap_style; /* CapNotLast, CapButt, CapRound, CapProjecting */ int join_style; /* JoinMiter, JoinRound, JoinBevel */ int fill_style; /* FillSolid, FillTiled, FillStippled FillOpaqueStippled*/ int fill_rule; /* EvenOddRule, WindingRule */ int arc_mode; /* ArcChord, ArcPieSlice */ Pixmap tile; /* tile pixmap for tiling operations */ Pixmap stipple; /* stipple 1 plane pixmap for stippling */ int ts_x_origin; /* offset for tile or stipple operations */ int ts_y_origin; Font font; /* default text font for text operations */ int subwindow_mode; /* ClipByChildren, IncludeInferiors */ Bool graphics_exposures; /* boolean, should exposures be generated */ int clip_x_origin; /* origin for clipping */ int clip_y_origin; Pixmap clip_mask; /* bitmap clipping; other calls for rects */ int dash_offset; /* patterned/dashed line information */ char dashes; } XGCValues; Use XCreateGC to create a new graphics context for the specified drawable. The definition for this function is: December 18, 1987 - 96 - GC XCreateGC(display, d, valuemask_create, values) Display *display; Drawable d; unsigned long valuemask_create; XGCValues *values; display Specifies the connection to the X server. d Specifies the drawable. valuemask_createSpecifies which components in the graphics context are to be set using information in the XGCValues structure. This argument is the bitwise inclusive OR of one or more of the valid GC com- ponent masks. values Specifies a pointer to the XGCValues structure. The XCreateGC function creates a graphics context and returns a GC. The graphics context can be used with any destination drawable having the same root and depth as the specified drawable. Use with other drawables results in a BadMatch error. The specified components of the new graphics context in valuemask_create are set to the values passed in the values argument. The other values default to the following values: __________________________________________________________________________________ Component Value __________________________________________________________________________________ function: GXcopy plane_mask: All ones foreground: 0 background: 1 line_width: 0 line_style: LineSolid cap_style: CapButt join_style: JoinMiter fill_style: FillSolid fill_rule: EvenOddRule arc_mode: ArcPieSlice tile: Pixmap of unspecified size filled with foreground pixel (that is, client specified pixel if any, else 0) (subsequent changes to foreground do not affect this pixmap) stipple: Pixmap of unspecified size filled with ones ts_x_origin: 0 ts_y_origin: 0 font: <implementation dependent> subwindow_mode: ClipByChildren graphics_exposures: True clip_x_origin: 0 clip_y_origin: 0 December 18, 1987 - 97 - __________________________________________________________________________________ Component Value __________________________________________________________________________________ clip_mask: None dash_offset: 0 dashes: 4 (that is, the list [4, 4]) __________________________________________________________________________________ Note that foreground and background are not set to any values likely to be useful on a color display. In graphics operations, given a source and destination pixel, the result is computed bitwise on corresponding bits of the pixels. That is, a boolean operation is performed in each bit plane. The plane_mask restricts the operation to a subset of planes. That is, the result is computed by the following: ((src FUNC dst) AND plane-mask) OR (dst AND (NOT plane-mask)) Range checking is not performed on the values for fore- ground, background, or plane_mask. They are simply trun- cated to the appropriate number of bits. The line_width is measured in pixels and either can be greater than or equal to one (wide line) or can be the special value zero (thin line). Wide lines are drawn centered on the path described by the graphics request. Unless otherwise specified by the join or cap style, the bounding box of a wide line with endpoints [x1, y1], [x2, y2], and width w is a rectangle with vertices at the following real coordinates: [x1-(w*sn/2), y1+(w*cs/2)], [x1+(w*sn/2), y1-(w*cs/2)], [x2-(w*sn/2), y2+(w*cs/2)], [x2+(w*sn/2), y2-(w*cs/2)] The sn is the sine of the angle of the line and cs is the cosine of the angle of the line. A pixel is part of the line and, hence, is drawn, if the center of the pixel is fully inside the bounding box (which is viewed as having infinitely thin edges). If the center of the pixel is exactly on the bounding box, it is part of the line if and only if the interior is immediately to its right (x increas- ing direction). Pixels with centers on a horizontal edge are a special case and are part of the line if and only if the interior is immediately below (y increasing direction). Thin lines (zero line_width) are one pixel wide lines drawn using an unspecified, device dependent algorithm. There are only two constraints on this algorithm. December 18, 1987 - 98 - 1. If a line is drawn unclipped from [x1,y1] to [x2,y2] and if another line is drawn unclipped from [x1+dx,y1+dy] to [x2+dx,y2+dy], a point [x,y] is touched by drawing the first line if and only if the point [x+dx,y+dy] is touched by drawing the second line. 2. The effective set of points comprising a line cannot be affected by clipping. That is, a point is touched in a clipped line if and only if the point lies inside the clipping region and the point would be touched by the line when drawn unclipped. A wide line drawn from [x1,y1] to [x2,y2] always draws the same pixels as a wide line drawn from [x2,y2] to [x1,y1], not counting cap and join styles. Implementors are encouraged to make this property true for thin lines, but it is not required. A line_width of zero may differ from a line_width of one in which pixels are drawn. In general, drawing a thin line will be faster than drawing a wide line of width one. However, because of their dif- ferent drawing algorithms, thin lines may not mix well, aesthetically speaking, with wide lines. If it is desirable to obtain precise and uniform results across all displays, a client should always use a line_width of one, rather than a line_width of zero. The line-style defines which sections of a line are drawn: LineSolid The full path of the line is drawn. LineDoub- leDash The full path of the line is drawn, but the even dashes are filled differently than the odd dashes (see fill-style) with CapButt style used where even and odd dashes meet. LineOnOff- Dash Only the even dashes are drawn, and cap-style applies to all internal ends of the indivi- dual dashes, except CapNotLast is treated as CapButt. The cap_style defines how the endpoints of a path are drawn: CapNotLast Equivalent to CapButt, except that for a line_width of zero or one the final endpoint is not drawn. CapButt Square at the endpoint (perpendicular to the slope of the line) with no projection beyond. CapRound A circular arc with the diameter equal to the line_width, centered on the endpoint December 18, 1987 - 99 - (equivalent to CapButt for line_width zero or one). CapProject- ing Square at the end, but the path continues beyond the endpoint for a distance equal to half the line_width (equivalent to CapButt for line_width zero or one). The join_style defines how corners are drawn for wide lines: JoinMiter The outer edges of two lines extend to meet at an angle. JoinRound A circular arc with diameter equal to the line_width, centered on the joinpoint. JoinBevel CapButt endpoint styles, and then the tri- angular notch filled. For a line with coincident endpoints (x1=x2, y1=y2), when the cap_style is applied to both endpoints, the semantics depends on the line_width and the cap_style: CapNotLast thin Device dependent, but the desired effect is that nothing is drawn. CapButt thin Device dependent, but the desired effect is that a single pixel is drawn. CapRound thin Same as CapButt/thin. CapProject- ing thin Same as Butt/thin. CapButt wide Nothing is drawn. CapRound wide The closed path is a circle, centered at the endpoint, with diameter equal to the line_width. CapRound thin Device dependent, but the desired effect is that a single pixel is drawn CapProject- ing wide The closed path is a square4, aligned with the coordinate axes, centered at the endpoint, with sides equal to the line_width CapProject- ing thin Device dependent, but the desired effect is that a single pixel is drawn For a line with coincident endpoints (x1=x2, y1=y2), when the join_style is applied at one or both endpoints, the effect is as if the line was removed from the overall path. However, if the total path consists of or is reduced to a single point joined with itself, the effect is the same as when the cap_style is applied at both endpoints. December 18, 1987 - 100 - The tile/stipple and clip origins are interpreted relative to the origin of whatever destination drawable is specified in a graphics request. The tile pixmap must have the same root and depth as the graphics context. Otherwise, a Bad- Match error is generated. The stipple pixmap must have depth one and must have the same root as the graphics con- text (else a BadMatch error). For stipple operations where the fill_style is FillStippled but not FillOpaqueStippled, the stipple pattern is tiled in a single plane and acts as an additional clip mask to be ANDed with the clip_mask. Any size pixmap can be used for tiling or stippling, although some sizes may be faster to use than others. The fill_style defines the contents of the source for line, text, and fill requests. For all text and fill requests (for example, XDrawText, XDrawText16, XFillRectangle, XFillPo- lygon, and XFillArc); for line requests (for example, XDraw- Line, XDrawSegments, XDrawRectangle, XDrawArc) with line_style LineSolid; and for the even dashes for line requests with line_style LineOnOffDash or LineDoubleDash the following apply: FillSolid Foreground. FillTiled Tile. FillOpaqueStip- pled A tile with the same width and height as stipple, but with background everywhere stipple has a zero and with foreground everywhere stipple has a one. FillStippled Foreground masked by stipple. When drawing lines with line_style LineDoubleDash, the odd dashes are controlled by the fill_style in the following manner: FillSolid Background. FillTiled Same as for even dashes. FillOpaqueStip- pled Same as for even dashes. FillStippled Background masked by stipple. Storing a pixmap in a graphics context might or might not result in a copy being made. If the pixmap is later used as the destination for a graphics request, the change might or might not be reflected in the graphics context. If the pix- map is used simultaneously in a graphics request both as a destination and as a tile or stipple, the results are not defined. It is quite likely that some amount of graphics context December 18, 1987 - 101 - information will be cached in display hardware and that such hardware can only cache a small number of graphics contexts. Given the number and complexity of components, clients should view switching between graphics contexts with nearly identical state as significantly more expensive than making minor changes to a single graphics context. The dash_list value allowed here is actually a simplified form of the more general patterns that can be set with XSet- Dashes. Specifying a value of N here is equivalent to specifying the two element list [N, N] in XSetDashes. The value must be nonzero. Otherwise, a BadValue error is gen- erated. The meaning of dash_offset and dash_list are explained for the XSetDashes function. The clip_mask restricts writes to the destination drawable. If a pixmap is specified as the clip_mask, it must have depth one and have the same root as the graphics context. Otherwise, a BadMatch error is generated. If clip_mask is None, the pixels are always drawn, regardless of the clip origin. The clip_mask can also be set with the XSetClipRec- tangles request. Only pixels where the clip-mask has a one bit are drawn. Pixels are not drawn outside the area covered by the clip_mask or where the clip_mask has a zero bit. It affects all graphics requests. The clip_mask does not clip sources. The clip_mask origin is interpreted relative to the origin of whatever destination drawable is specified in a graphics request. For ClipByChildren, both source and destination windows are additionally clipped by all viewable InputOutput children. For IncludeInferiors, neither source nor destination window is clipped by inferiors. This will result in drawing through subwindow boundaries. The use of IncludeInferiors on a win- dow of one depth with mapped inferiors of differing depth is not illegal, but the semantics are undefined by the core protocol. The fill_rule defines what pixels are inside (drawn) for paths given in XFillPolygon requests. EvenOddRule means a point is inside if an infinite ray with the point as origin crosses the path an odd number of times. For WindingRule, a point is inside if an infinite ray with the point as origin crosses an unequal number of clockwise and counterclockwise directed path segments. A clockwise directed path segment is one which crosses the ray from left to right as observed from the point. A counterclockwise segment is one which crosses the ray from right to left as observed from the point. The case where a directed line segment is coincident with the ray is uninteresting because you can simply choose a different ray that is not coincident with a segment. December 18, 1987 - 102 - For both EvenOddRule and WindingRule, a point is infinitely small, and the path is an infinitely thin line. A pixel is inside if the center point of the pixel is inside, and the center point is not on the boundary. If the center point is on the boundary, the pixel is inside if and only if the polygon interior is immediately to its right (x increasing direction). Pixels with centers along a horizontal edge are a special case and are inside if and only if the polygon interior is immediately below (y increasing direction). The arc_mode controls filling in the XFillArcs function and can be one of the constants ArcPieSlice or ArcChord. The graphics_exposure flag controls GraphicsExpose event genera- tion for XCopyArea and XCopyPlane requests (and any similar requests defined by extensions). The other event errors that can be generated by XCreateGC are BadDrawable, BadPixmap, BadAlloc, BadMatch, and BadFont. Use XCopyGC to copy components from a source graphics con- text to a destination graphics context. The definition for this function is: XCopyGC(display, src, valuemask_copy, dest) Display *display; GC src, dest; unsigned long valuemask_copy; display Specifies the connection to the X server. src Specifies the components of the source graphics context. valuemask_copySpecifies which components in the source graphics context are to be copied to the destina- tion graphics context. This argument is the bit- wise inclusive OR of one or more of the valid GC component masks. dest Specifies the destination graphics context. The XCopyGC function copies the specified components from the source graphics context to the destination graphics con- text. The source and destination graphics contexts must have the same root and depth. Otherwise, a BadMatch error is generated. The valuemask_copy specifies which component to copy, as for XCreateGC. The other event errors that can be generated by XCopyGC are BadGC, BadAlloc, and BadValue. December 18, 1987 - 103 - Use XChangeGC to change the components in the specified graphics context. The definition for this function is: XChangeGC(display, gc, valuemask_change, values) Display *display; GC gc; unsigned long valuemask_change; XGCValues *values; display Specifies the connection to the X server. gc Specifies the graphics context. valuemask_changeSpecifies which components in the graphics context are to be changed using information in the XGCValues structure. This argument is the bitwise inclusive OR of one or more of the valid GC com- ponent masks. values Specifies a pointer to the XGCValues structure. The XChangeGC function changes the components specified by the valuemask_change argument for the specified graphics context. The values argument contains the values to be set. The values and restrictions are the same as for XCreateGC. Changing the clip_mask also overrides any previous XSetClipRectangles request on the context. Changing the dash_offset or dash_list overrides any previous XSetDashes request on the context. The order in which components are verified and altered is sever-dependent. If an error is generated, a subset of the components may have been altered. The errors that can be generated by XChangeGC are BadGC, BadPixmap, BadFont, BadMatch, BadAlloc, and BadValue. Use XFreeGC to free the specified graphics context. The definition for this function is: XFreeGC(display, gc) Display *display; GC gc; display Specifies the connection to the X server. gc Specifies the graphics context. The XFreeGC function destroys the specified graphics context as well as the shadow copy. The error that can be generated by XFreeGC is BadGC. December 18, 1987 - 104 - 5.4. Using GC Convenience Routines Xlib provides functions with which you can set a graphics context component. This section discusses how to set the: o Foreground, background, plane mask, or function com- ponents o Line attributes and dashes components o Fill style and fill rule components o Fill tile and stipple components o Font component o Clip region component o Arc mode, subwindow mode, and graphics exposure com- ponents 5.4.1. Setting Foreground, Background, Plane Mask, or Func- tion Use XSetState to set the foreground, background, plane mask, and function components for the specified graphics context. The definition for this function is: XSetState(display, gc, foreground, background, function, plane_mask) Display *display; GC gc; unsigned long foreground, background; int function; unsigned long plane_mask; display Specifies the connection to the X server. gc Specifies the graphics context. foregroundSpecifies the foreground you want to set for the specified graphics context. backgroundSpecifies the background you want to set for the specified graphics context. function Specifies the function you want to set for the specified graphics context. plane_maskSpecifies the plane mask. The errors that can be generated by XSetState are BadGC and BadValue. December 18, 1987 - 105 - Use XSetFunction to set a specified value in the specified graphics context. The definition for this function is: XSetFunction(display, gc, function) Display *display; GC gc; int function; display Specifies the connection to the X server. gc Specifies the graphics context. function Specifies the function you want to set for the specified graphics context. The errors that can be generated by XSetFunction are BadGC and BadValue. Use XSetPlaneMask to set the plane mask in the specified graphics context. The definition for this function is: XSetPlaneMask(display, gc, plane_mask) Display *display; GC gc; unsigned long plane_mask; display Specifies the connection to the X server. gc Specifies the graphics context. plane_maskSpecifies the plane mask. The error that can be generated by XSetPlaneMask is BadGC. Use XSetForeground to set the foreground in the specified graphics context. The definition for this function is: XSetForeground(display, gc, foreground) Display *display; GC gc; unsigned long foreground; display Specifies the connection to the X server. gc Specifies the graphics context. foregroundSpecifies the foreground you want to set for the specified graphics context. December 18, 1987 - 106 - The error that can be generated by XSetForeground is BadGC. Use XSetBackground to set the background in the specified graphics context. The definition for this function is: XSetBackground(display, gc, background) Display *display; GC gc; unsigned long background; display Specifies the connection to the X server. gc Specifies the graphics context. backgroundSpecifies the background you want to set for the specified graphics context. The error that can be generated by XSetBackground is BadGC. 5.4.2. Setting Line Attributes and Dashes Use XSetLineAttributes to set the line drawing components in the specified graphics context. The definition for this function is: XSetLineAttributes(display, gc, line_width, line_style, cap_style, join_style) Display *display; GC gc; unsigned int line_width; int line_style; int cap_style; int join_style; display Specifies the connection to the X server. gc Specifies the graphics context. line_widthSpecifies the line width you want to set for the specified graphics context. line_styleSpecifies the line style you want to set for the specified graphics context. Possible values are LineSolid (solid), LineOnOffDash (on-off dash), or LineDoubleDash (double dash). cap_style Specifies the line and cap style you want to set for the specified graphics context. Possible values are CapNotLast, CapButt, CapRound, or Cap- Projecting. December 18, 1987 - 107 - join_styleSpecifies the line-join style you want to set for the specified graphics context. Possible values are JoinMiter, JoinRound, or JoinBevel. The errors that can be generated by XSetLineAttributes are BadGC and BadValue. Use XSetDashes to set the dash_offset and dash_list for dashed line styles in the specified graphics context. The definition for this function is: XSetDashes(display, gc, dash_offset, dash_list, n) Display *display; GC gc; int dash_offset; char dash_list[]; int n; display Specifies the connection to the X server. gc Specifies the graphics context. dash_offsetSpecifies the phase of the pattern for the dashed line style you want to set for the specified graphics context. dash_list Specifies the dash list for the dashed line style you want to set for the specified graphics con- text. n Specifies the length of the dash list argument. The XSetDashes function sets the dash_offset and dash_list in the specified GC for dashed line styles. Dashes cannot be empty. Otherwise, a BadValue error is generated. The initial and alternating elements of the dash_list are the even dashes, the others are the odd dashes. All of the ele- ments must be nonzero. Otherwise, a BadValue error is gen- erated. Specifying an odd-length list is equivalent to specifying the same list concatenated with itself to produce an even-length list. You probably will find it easiest to specify the elements of the dash_list as octal or hex values. The dash_offset defines the phase of the pattern, specifying how many ele- ments into the dash_list the pattern should actually begin in any single graphics request. N specifies the length of the dash_list. Dashing is continuous through path elements combined with a join_style, but is reset to the dash_offset each time a cap_style is applied at a line endpoint. The unit of measure for dashes is the same as in the December 18, 1987 - 108 - ordinary coordinate system. Ideally, a dash length is meas- ured along the slope of the line, but implementations are only required to match this ideal for horizontal and verti- cal lines. Failing the ideal semantics, it is suggested that the length be measured along the major axis of the line. The major axis is defined as the x axis for lines drawn at an angle of between -45 and +45 degrees or between 315 and 225 degrees from the x axis. For all other lines, the major axis is the y axis. The default dash_list in a newly created GC is equivalent to `` 04 04''. The other event errors that can be generated by XSetDashes are BadAlloc and BadGC. 5.4.3. Setting the Fill Style and File Rule Components Use XSetFillStyle to set the fill style in the specified graphics context. The definition for this function is: XSetFillStyle(display, gc, fill_style) Display *display; GC gc; int fill_style; display Specifies the connection to the X server. gc Specifies the graphics context. fill_styleSpecifies the fill style you want to set for the specified graphics context. Possible values are FillSolid, FillTiled, FillStippled, or FillOpa- queStippled. The errors that can be generated by XSetFillStyle are BadGC and BadValue. Use XSetFillRule to set the fill rule in the specified graphics context. The definition for this function is: XSetFillRule(display, gc, fill_rule) Display *display; GC gc; int fill_rule; display Specifies the connection to the X server. gc Specifies the graphics context. fill_rule Specifies the fill rule you want to set for the specified graphics context. You can pass one of these constants: EvenOddRule or WindingRule. December 18, 1987 - 109 - The errors that can be generated by XSetFillRule are BadGC and BadValue. 5.4.4. Setting the Fill Tile and Stipple Components Some hardware can support specific size patterns for tiling or stippling that runs much faster than arbitrary sizes. Xlib provides functions with which you can determine the best size, tile, or stipple for the display as well as set the tile or stipple shape and the tile/stipple origin. Use XQueryBestSize to obtain the best size. The definition for this function is: Status XQueryBestSize(display, class, which_screen, width, height, width_return, height_return) Display *display; int class; Drawable which_screen; unsigned int width, height; unsigned int *width_return, *height_return; display Specifies the connection to the X server. class Specifies the class that you are interested in. You can pass one of these constants: TileShape, CursorShape, or StippleShape. which_screenSpecifies any drawable on a screen. width height Specify the width and height. width_return height_returnReturns the width and height of the object best supported by the display hardware. The XQueryBestSize function returns the best or closest size to the specified size. For CursorShape, this is the largest size that can be fully displayed on the screen specified by which_screen. For TileShape, this is the size that can be tiled fastest. For StippleShape, this is the size that can be stippled fastest. For CursorShape, the drawable indi- cates the desired screen. For TileShape and StippleShape, the drawable indicates the screen and possibly the window class and depth. An InputOnly window cannot be used as the drawable for TileShape or StippleShape. Otherwise, a Bad- Match error is generated. The other event errors that can be generated by XQueryBest- Size are BadDrawable, BadMatch, and BadValue. December 18, 1987 - 110 - Use XQueryBestTile to obtain the best fill tile shape. The definition for this function is: Status XQueryBestTile(display, which_screen, width, height, width_return, height_return) Display *display; Drawable which_screen; unsigned int width, height; unsigned int *width_return, *height_return; display Specifies the connection to the X server. which_screenSpecifies any drawable on a screen. width height Specify the width and height. width_return height_returnReturns the width and height of the object best supported by the display hardware. The XQueryBestTile function returns the best or closest size, that is, the size that can be tiled fastest on the screen specified by which_screen. The drawable indicates the screen and possibly the window class and depth. An InputOnly window cannot be used as the drawable for XQuer- yBestTile. Otherwise, a BadMatch error is generated. The other error that can be generated by XQueryBestTile is BadDrawable. Use XQueryBestStipple to obtain the best stipple shape. The definition for this function is: Status XQueryBestStipple(display, which_screen, width, height, width_return, height_return) Display *display; Drawable which_screen; unsigned int width, height; unsigned int *width_return, *height_return; display Specifies the connection to the X server. which_screenSpecifies any drawable on a screen. width height Specify the width and height. width_return height_returnReturns the width and height of the object best supported by the display hardware. The XQueryBestStipple function returns the best or closest December 18, 1987 - 111 - size, that is, the size that can be stippled fastest on the screen specified by which_screen. The drawable indicates the screen and possibly the window class and depth. An InputOnly window cannot be used as the drawable for XQuer- yBestStipple. Otherwise, a BadMatch error is generated. The other error that can be generated by XQueryBestStipple is BadDrawable. Use XSetTile to set the fill tile in the specified graphics context. The definition for this function is: XSetTile(display, gc, tile) Display *display; GC gc; Pixmap tile; display Specifies the connection to the X server. gc Specifies the graphics context. tile Specifies the fill tile you want to set for the specified graphics context. The errors that can be generated by XSetTile are BadGC, Bad- Pixmap, BadMatch, and BadAlloc. Use XSetStipple to set the stipple in the specified graphics context. The definition for this function is: XSetStipple(display, gc, stipple) Display *display; GC gc; Pixmap stipple; display Specifies the connection to the X server. gc Specifies the graphics context. stipple Specifies the stipple you want to set for the specified graphics context. The errors that can be generated by XSetStipple are BadGC, BadPixmap, BadMatch, and BadAlloc. Use XSetTSOrigin to set the tile or stipple origin in the specified graphics context. The definition for this func- tion is: December 18, 1987 - 112 - XSetTSOrigin(display, gc, ts_x_origin, ts_y_origin) Display *display; GC gc; int ts_x_origin, ts_y_origin; display Specifies the connection to the X server. gc Specifies the graphics context. ts_x_origin ts_y_originSpecify the x and y coordinates of the tile or stipple origin. The error that can be generated by XSetTSOrigin is BadGC. 5.4.5. Setting the Current Font Use XSetFont to set the current font in the specified graph- ics context. The definition for this function is: XSetFont(display, gc, font) Display *display; GC gc; Font font; display Specifies the connection to the X server. gc Specifies the graphics context. font Specifies the font ID. The errors that can be generated by XSetFont are BadGC, Bad- Font, and BadAlloc. 5.4.6. Setting Clip Region Xlib provides functions with which you can set the clip ori- gin or the clip mask as well as with which you can set the clip mask to a list of rectangles. Use XSetClipOrigin to set the clip origin in the specified graphics context. The definition for this function is: XSetClipOrigin(display, gc, clip_x_origin, clip_y_origin) Display *display; GC gc; int clip_x_origin, clip_y_origin; December 18, 1987 - 113 - display Specifies the connection to the X server. gc Specifies the graphics context. clip_x_origin clip_y_originSpecify the x and y coordinates of the clip origin. The error that can be generated by XSetClipOrigin is BadGC. Use XSetClipMask to set the clip_mask in the specified graphics context to the specified pixmap. The definition for this function is: XSetClipMask(display, gc, pixmap) Display *display; GC gc; Pixmap pixmap; display Specifies the connection to the X server. gc Specifies the graphics context. pixmap Specifies the pixmap. The errors that can be generated by XSetClipMask are BadGC, BadMatch, and BadValue. Use XSetClipRectangles to change the clip_mask in the speci- fied graphics context to the specified list of rectangles. The definition for this function is: XSetClipRectangles(display, gc, clip_x_origin, clip_y_origin, rectangles, n, ordering) Display *display; GC gc; int clip_x_origin, clip_y_origin; XRectangle rectangles[]; int n; int ordering; display Specifies the connection to the X server. gc Specifies the graphics context. clip_x_origin clip_y_originSpecify the x and y coordinates of the clip origin. December 18, 1987 - 114 - rectanglesSpecifies an array of rectangles. These are the rectangles you want to specify in the graphics context. n Specifies the number of rectangles. ordering Specifies the ordering relations on the rectan- gles. Possible values are Unsorted, YSorted, YXSorted, or YXBanded. The XSetClipRectangles function changes the clip_mask in the specified graphics context to the specified list of rectan- gles and sets the clip origin. The output is clipped to remain contained within the rectangles. The number of rec- tangles are specified with the n argument. The clip origin is interpreted relative to the origin of whatever destina- tion drawable is specified in a graphics request. The rec- tangle coordinates are interpreted relative to the clip ori- gin. The rectangles should be nonintersecting, or the graph- ics results will be undefined. Note that the list of rec- tangles can be empty, which effectively disables output. This is the opposite of passing None as the clip_mask in XCreateGC and XChangeGC. If known by the client, ordering relations on the rectangles can be specified with the ordering argument. This may pro- vide faster operation by the server. If an incorrect order- ing is specified, the X server may generate a BadMatch error, but it is not required to do so. If no error is gen- erated, the graphics results are undefined. Unsorted means the rectangles are in arbitrary order. YSorted means that the rectangles are nondecreasing in their Y origin. YXSorted additionally constrains YSorted order in that all rectangles with an equal Y origin are nondecreasing in their X origin. YXBanded additionally constrains YXSorted by requiring that, for every possible Y scan line, all rectan- gles that include that scan line have an identical Y origins and Y extents. The other event errors that can be generated by XSetClipRec- tangles are BadGC, BadAlloc, and BadValue. Note The Xlib library provides a set of basic functions for performing region arithmetic. For information about these functions, see Chapter 10. 5.4.7. Setting the Arc Mode, Subwindow Mode, and Graphics Exposure components Use XSetArcMode to set the arc mode in the specified graph- ics context. The definition for this function is: December 18, 1987 - 115 - XSetArcMode(display, gc, arc_mode) Display *display; GC gc; int arc_mode; display Specifies the connection to the X server. gc Specifies the graphics context. arc_mode Specifies the arc mode: ArcChord specifies that arcs will be chord filled, while ArcPieSlice specifies that arcs will be pie slice filled. The errors that can be generated by XSetArcMode are BadGC and BadValue. Use XSetSubwindowMode to set the subwindow mode in the specified graphics context. The definition for this function is: XSetSubwindowMode(display, gc, subwindow_mode) Display *display; GC gc; int subwindow_mode; display Specifies the connection to the X server. gc Specifies the graphics context. subwindow_modeSpecifies the subwindow mode: ClipByChildren clips source and destination by all viewable chil- dren, while IncludeInferiors draws through all subwindows, that is, does not clip by inferiors. The errors that can be generated by XSetSubwindowMode are BadGC and BadValue. Use XSetGraphicsExposures to set the graphics-exposures flag in the specified graphics context. The definition for this function is: XSetGraphicsExposures(display, gc, graphics_exposures) Display *display; GC gc; Boolean graphics_exposures; display Specifies the connection to the X server. December 18, 1987 - 116 - gc Specifies the graphics context. graphics_exposuresSpecifies whether you want GraphicsExpose events to be reported when calling XCopyArea and XCopyPlane with this graphics context. If True, GraphicsExpose events are reported. If False, GraphicsExpose events are not reported. The errors that can be generated by XSetGraphicsExposures are BadGC and BadValue. December 18, 1987 - 117 - Chapter 6 Graphics Functions Chapter 6 - Graphics Functions Once you have connected the display to the X server, you can use the Xlib graphics func- tions to: o Clear and copy areas o Draw points, lines, rectangles, and arcs o Fill areas o Manipulate fonts o Draw text characters o Transfer images between clients and server o Manipulate cursors Note It is generally more efficient to call those graphics functions that take an array of arguments (for example, XDrawPoints) once than it is to call those graphics functions that do not (for example, XDrawPoint) a number of times. 6.1. Clearing Areas Xlib provides functions with which you can clear an area or the entire drawable. Because pixmaps do not have defined backgrounds, they cannot be filled by using the functions described in this section. Instead, to accomplish an analo- gous operation on a pixmap, you should use XFillRectangle, which sets the pixmap to a known value. See Section 6.4.1 for information on XFillRectangle. Use XClearArea to clear a specified rectangular area in the specified window. The definition for this function is: December 18, 1987 - 118 - XClearArea(display, w, x, y, width, height, exposures) Display *display; Window w; int x, y; unsigned int width, height; Bool exposures; display Specifies the connection to the X server. w Specifies the window ID. x y Specify the x and y coordinates. These coordi- nates are relative to the origin of the window and specify the upper left corner of the rectangle. width height Specify the width and height. These are the dimensions of the rectangle to be cleared. exposures Specifies a boolean value of True or False. The XClearArea function clears a rectangular area in the specified window according to the specified dimensions. If width is zero, it is replaced with the current width of the window minus x. If height is zero, it is replaced with the current height of the window minus y. If the window has a defined background tile, the rectangle is filled with this tile. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, one or more exposure events are generated for regions of the rectangle that are either visible or are being retained in a backing store. A BadMatch error is generated if you specify a window whose class is InputOnly. The other event errors that can be generated by XClearArea are BadWindow, BadMatch, and BadValue. Use XClearWindow to clear the entire area in the specified window. The definition for this function is: XClearWindow(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XClearWindow function clears the entire area in the specified window and is equivalent to XClearArea (display, December 18, 1987 - 119 - w, 0, 0, 0, 0, False). If the window has a defined back- ground tile, the rectangle is tiled with a plane-mask of all ones and function of GXcopy. If the window has background None, the contents of the window are not changed. In either case, if exposures is True, one or more exposure events are generated for regions of the rectangle that are either visi- ble or are being retained in a backing store. A BadMatch error is generated if you specify a window whose class is InputOnly. The other event errors that can be generated by XClearWindow are BadWindow, BadMatch, and BadValue. 6.2. Copying Areas Xlib provides functions with which you can copy an area or a bit-plane. Use XCopyArea to copy an area of the specified drawable between drawables of the same root and depth. The defini- tion for this function is: XCopyArea(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y; display Specifies the connection to the X server. src dest Specify the source and destination rectangles to be combined. gc Specifies the graphics context. src_x src_y Specify the x and y coordinates of the source rec- tangle relative to its origin. These coordinates specify the upper left corner of the source rec- tangle. width height Specify the width and height. These are the dimensions of both the source and destination rec- tangles. dest_x December 18, 1987 - 120 - dest_y Specify the x and y coordinates of the destination rectangle relative to its origin. These coordi- nates specify the upper left corner of the desti- nation rectangle. The XCopyArea function combines the specified rectangle of src with the specified rectangle of dest. The rectangles specified by these two arguments must have the same root and depth. Otherwise, a BadMatch error is generated. XCopyArea uses these graphics context components: function, plane_mask, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and clip_mask. If either the regions of the source rectangle are obscured and have not been retained in backing_store or the regions outside the boundaries of the source drawable are specified, those regions are not copied. Instead, the following occurs on all corresponding destination regions that are either visible or are retained in backing_store. If the destination rectangle is a window with a background other than None, these corresponding regions of the destination are tiled (with plane_mask of all ones and function GXcopy) with that background. Regardless of tiling or whether the destination is a window or a pixmap, if graphics_exposures in GC is True, then GraphicsExpose events for all corresponding des- tination regions are generated. If graphics_exposures is True but no regions are exposed, a NoExpose event is gen- erated. Note that by default, graphics_exposures is True on in new GCs. See Chapter 8 for further information. The errors that can be generated by XCopyArea are BadDraw- able, BadGC, and BadMatch. Use XCopyPlane to copy a single bit-plane of the specified drawable. The drawable may have different depths. The definition for XCopyPlane is: XCopyPlane(display, src, dest, gc, src_x, src_y, width, height, dest_x, dest_y, plane) Display *display; Drawable src, dest; GC gc; int src_x, src_y; unsigned int width, height; int dest_x, dest_y; unsigned long plane; display Specifies the connection to the X server. src dest Specify the source and destination rectangles to be combined. December 18, 1987 - 121 - gc Specifies the graphics context. src_x src_y Specify the x and y coordinates of the source rec- tangle relative to its origin. These coordinates specify the upper left corner of the source rec- tangle. width height Specify the width and height. These are the dimensions of both the source and destination rec- tangles. dest_x dest_y Specify the x and y coordinates of the destination rectangle relative to its origin. These coordi- nates specify the upper left corner of the desti- nation rectangle. plane Specifies the bit-plane. You must set exactly one bit. The XCopyPlane function combines a single bit plane of the specified rectangle of src with the specified rectangle of dest. The rectangles specified by these two arguments must have the same root but need not have the same depth. If the rectangles do not have the same root, a BadMatch error is generated. This function is identical to XCopyArea, except that only one bit-plane is copied. If the bit-plane does not have exactly one bit set, a BadValue error is generated. Effectively, the function forms a pixmap of the same depth as the rectangle of dest and with a size specified by the source region. The function uses the foreground/background pixels in the graphics context (foreground everywhere the bit-plane in src contains a one bit, background everywhere the bit-plane in src contains a zero bit) and the equivalent of a XCopyArea request is performed with all the same expo- sure semantics. This can also be thought of as using the specified region of the source bit-plane as a stipple with a fill_style of FillOpaqueStippled for filling a rectangular area of the destination. Regardless of tiling or whether the destination is a window or a pixmap, if graphics_exposures in GC is True, the Gra- phicsExpose events for all corresponding destination regions are generated. If graphics_exposures is True but no regions are exposed, a NoExpose event is generated. Note that by default, graphics_exposures is True on in new GCs. See Chapter 8 for further information. XCopyPlane uses these graphics context components: function, plane_mask, foreground, background, subwindow_mode, graphics_exposures, clip_x_origin, clip_y_origin, and December 18, 1987 - 122 - clip_mask. The other event errors that can be generated by XCopyPlane are BadDrawable, BadMatch, BadValue, and BadGC. 6.3. Drawing Points, Lines, Rectangles, and Arcs Xlib provides functions with which you can draw: o A single point or multiple points o A single line or multiple lines o A single rectangle or multiple rectangles o A single arc or multiple arcs Some of the functions described in the following subsections use these structures: typedef struct { short x1, y1, x2, y2; } XSegment; typedef struct { short x, y; } XPoint; typedef struct { short x, y; unsigned short width, height; } XRectangle; typedef struct { short x, y; unsigned short width, height; short angle1, angle2; /* Degrees * 64 */ } XArc; All x and y members are signed integers. The width and height members are 16-bit unsigned integers. Applications should be careful not to generate coordinates and sizes out of the 16-bit ranges, as the protocol only has 16 bit fields for these values. 6.3.1. Drawing Single and Multiple Points Use XDrawPoint to draw a single point or XDrawPoints to draw multiple points in the specified drawable. The definition for XDrawPoint is: December 18, 1987 - 123 - XDrawPoint(display, d, gc, x, y) Display *display; Drawable d; GC gc; int x, y; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates where you want the point drawn. The definition for XDrawPoints is: XDrawPoints(display, d, gc, points, npoints, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int mode; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. points Specifies a pointer to an array of points. npoints Specifies the number of points in the array. mode Specifies the coordinate mode. CoordModeOrigin treats a coordinates as related to the origin, while CoordModePrevious treates all coordinates after the first as relative to the previous point. The XDrawPoint and XDrawPoints functions use these graphics context components: function, plane_mask, foreground, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The XDrawPoint function uses the foreground pixel and func- tion components of the graphics context to draw a single point into the specified drawable, while XDrawPoints draws multiple points into the specified drawable. These func- tions are not affected by the tile or stipple in the graph- ics context. December 18, 1987 - 124 - When using XDrawPoint, you simply specify the x and y coor- dinates where you want the point drawn. For XDrawPoints, you specify an array of XPoint structures, each of which contains an x and y coordinate. XDrawPoints draws the points in the order listed in the array. XDrawPoints requires a mode argument that indicates whether the points are relative to the drawable's origin or to the previous point: o If mode is CoordModeOrigin, all points after the first are relative to the drawable's origin. (The first point is always relative to the drawable's origin.) o If mode is CoordModePrevious, all points after the first are relative to the previous point. The errors that can be generated by XDrawPoint are BadDraw- able, BadGC, and BadMatch. The errors that can be generated by XDrawPoint are BadDrawable, BadGC, BadValue, and Bad- Match. 6.3.2. Drawing Single and Multiple Lines Use XDrawLine to draw a single line between two points in the specified drawable, XDrawLines to draw multiple lines in the specified drawable, or XDrawSegments to draw multiple, but not necessarily connected lines in the specified draw- able. The definition for XDrawLine is: XDrawLine(display, d, gc, x1, y1, x2, y2) Display *display; Drawable d; GC gc; int x1, y1, x2, y2; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x1 y1 x2 y2 Specify the points used to connect the line. Thus, XDrawLine draws a line connecting point x1, y1 to point x2, y2. The definition for XDrawLines is: December 18, 1987 - 125 - XDrawLines(display, d, gc, points, npoints, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int mode; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. points Specifies a pointer to an array of points. npoints Specifies the number of points in the array. mode Specifies the coordinate mode. CoordModeOrigin treats a coordinates as related to the origin, while CoordModePrevious treates all coordinates after the first as relative to the previous point. The definition for XDrawSegments is: XDrawSegments(display, d, gc, segments, nsegments) Display *display; Drawable d; GC gc; XSegment *segments; int nsegments; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. segments Specifies a pointer to an array of segments. nsegments Specifies the number of segments in the array. The XDrawLine function uses the components of the specified graphics context to draw a line between the specified set of points (x1, y1 and x2, y2). No joining is performed at coincident end points. For any given line, no pixel is drawn more than once. If lines intersect, the intersecting pixels are drawn multiple times. The XDrawLines function uses the components of the specified graphics context to draw npoints-1 lines between each pair December 18, 1987 - 126 - of points (point[i], point[i+1]) in the array of XPoint structures. The lines are drawn in the order listed in the array. The lines join correctly at all intermediate points, and if the first and last points coincide, the first and last lines also join correctly. For any given line, no pixel is drawn more than once. If thin (zero line width) lines intersect, the intersecting pixels will be drawn mul- tiple times. If wide lines intersect, the intersecting pix- els are drawn only once, as though the entire PolyLine were a single filled shape. XDrawLines requires a mode argument to determine whether the points are relative to the drawable's origin or to the previous point: o If mode is CoordModeOrigin, all points after the first are relative to the drawable's origin. (The first point is always relative to the drawable's origin.) o If mode is CoordModePrevious, all points after the first are relative to the previous point. The XDrawSegments function draws multiple, but not neces- sarily connected lines. For each segment, XDrawSegments draws a line between (x1, y1) and (x2, y2). The lines are drawn in the order listed in the array of XSegment struc- tures. No joining is performed at coincident end points. For any given line, no pixel is drawn more than once. If lines intersect, the intersecting pixels are drawn multiple times. All three functions use these graphics context components: function, plane_mask, line_width, line_style, cap_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The XDrawLines function also uses the join_style graphics context component. Additionally, all three functions use these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list. See the general discussion under XCreateGC in Chapter 5. The errors that can be generated by XDrawLine, XDrawLines, and XDrawSegments are BadDrawable, BadGC, and BadMatch. XDrawLines can also return BadValue. 6.3.3. Drawing Single and Multiple Rectangles Use XDrawRectangle to draw the outline of a single rectangle or XDrawRectangles to draw the outline of multiple rectan- gles in the specified drawable. The definition for XDrawRectangle is: December 18, 1987 - 127 - XDrawRectangle(display, d, gc, x, y, width, height) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates that define the upper left corner of the rectangle. width height Specify the width and height that define the out- line of the rectangle. The definition for XDrawRectangles is: XDrawRectangles(display, d, gc, rectangles, nrectangles) Display *display; Drawable d; GC gc; XRectangle rectangles[]; int nrectangles; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. rectanglesSpecifies a pointer to an array of rectangles. nrectanglesSpecifies the number of rectangles in the array. The XDrawRectangle and XDrawRectangles functions draw the outlines of the specified rectangle or rectangles as if a five-point PolyLine were specified for each rectangle: [x,y,] [x+width,y] [x+width,y+height] [x,y+height] [x,y] For the specified rectangle or rectangles, no pixel is drawn more than once. The x and y coordinates of each rectangle are relative to the drawable's origin and define the upper left corner of the rectangle. XDrawRectangles draws the December 18, 1987 - 128 - rectangles in the order listed in the array. If rectangles intersect, the intersecting pixels are drawn multiple times. XDrawRectangle and XDrawRectangles use these graphics con- text components: function, plane_mask, line_width, line_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. Both functions also use these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list. See the general discussion under XCreateGC in Chapter 5. The errors that can be generated by XDrawRectangle and XDrawRectangles are BadDrawable, BadGC, and BadMatch. 6.3.4. Drawing Single and Multiple Arcs Use XDrawArc to draw a single arc or XDrawArcs to draw mul- tiple arcs in the specified drawable. The definition for XDrawArc is: XDrawArc(display, d, gc, x, y, width, height, angle1, angle2) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height; int angle1, angle2; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These are the coordinates of the arc and are relative to the origin of the drawable. These coordinates also specify the upper left corner of the rectangle. width height Specify the width and height. These are the major and minor axes of the arc. angle1 Specifies the start of the arc relative to the three-o-clock position from the center, in units of degrees * 64. December 18, 1987 - 129 - angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. The definition for XDrawArcs is: XDrawArcs(display, d, gc, arcs, narcs) Display *display; Drawable d; GC gc; XArc *arcs; int narcs; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. arcs Specifies a pointer to an array of arcs. narcs Specifies the number of arcs in the array. XDrawArc draws a single circular or elliptical arc, while XDrawArcs draws multiple circular or elliptical arcs. Each arc is specified by a rectangle and two angles. The x and y coordinates are relative to the origin of the drawable and define the upper left corner of the rectangle. The center of the circle or ellipse is the center of the rectangle, and the major and minor axes are specified by the width and height, respectively. The angles are signed integers in degrees scaled by 64 with positive indicating counterclock- wise motion and negative indicating clockwise motion. The start of the arc is specified by angle1 relative to the three-o-clock position from the center of the rectangle, and the path and extent of the arc are specified by angle2 rela- tive to the start of the arc. If the magnitude of angle2 is greater than 360 degrees, XDrawArc or XDrawArcs truncates it to 360 degrees. The x and y coordinates of the rectangle are relative to the origin of the drawable. For an arc specified as [x,y,w,h,a1,a2], the origin of the major and minor axes is at [x+(w/2),y+(h/2)], and the infinitely thin path describ- ing the entire circle or ellipse intersects the horizontal axis at [x,y+(h/2)] and [x+w,y+(h/2)] and intersects the vertical axis at [x+(w/2),y] and [x+(w/2),y+h]. These coor- dinates can be fractional. That is, they are not truncated to discrete coordinates. The path should be defined by the ideal mathematical path. For a wide line with line-width lw, the bounding outlines for filling are given by the infin- itely thin paths describing the arcs: December 18, 1987 - 130 - [x+dx/2,y+dy/2,w-dx,h-dy,a1,a2] and [x-lw/2,y-lw/2,w+lw,h+lw,a1,a2] where dx=min(lw,w) dy=min(lw,h) For an arc specified as [x,y,w,h,a1,a2], the angles must be specified in the effectively skewed coordinate system of the ellipse (for a circle, the angles and coordinate systems are identical). The relationship between these angles and angles expressed in the normal coordinate system of the screen (as measured with a protractor) is as follows: skewed-angle = atan(tan(normal-angle) * w/h) + adjust The skewed-angle and normal-angle are expressed in radians (rather than in degrees scaled by 64) in the range [0,2*PI), and where atan returns a value in the range [-PI/2,PI/2], and where adjust is: 0 for normal-angle in the range [0,PI/2) PI for normal-angle in the range [PI/2,(3*PI)/2) 2*PI for normal-angle in the range [(3*PI)/2,2*PI) In the case of XDrawArc, you simply specify a single arc. For XDrawArcs, you specify an array of XArc structures, each of which contains an arc's x and y coordinates, width and height, start position, and path and extent. XDrawArcs draws the arcs in the order listed in the array. For any given arc, no pixel is drawn more than once. If two arcs join correctly and if the line_width is greater than zero and the arcs intersect, no pixel is drawn more than once. Otherwise, the intersecting pixels of intersecting arcs are drawn multiple times. Specifying an arc with one endpoint and a clockwise extent draws the same pixels as specifying the other endpoint and an equivalent counterclockwise extent, except as it affects joins. If the last point in one arc coincides with the first point in the following arc, the two arcs will join correctly. If the first point in the first arc coincides with the last point in the last arc, the two arcs will join correctly. By specifying one axis to be zero, a horizontal or vertical line can be drawn. Angles are computed based solely on the coordinate system and ignore the aspect ratio. December 18, 1987 - 131 - XDrawArc and XDrawArcs use these graphics context com- ponents: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. Both functions also use these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, ts_y_origin, dash_offset, and dash_list. The errors that can be generated by XDrawArc and XDrawArcs are BadDrawable, BadGC, and BadMatch. 6.4. Filling Areas Xlib provides functions with which you can fill: o A single rectangle or multiple rectangles o A single polygon o A single arc or multiple arcs 6.4.1. Filling Single and Multiple Rectangles Use XFillRectangle to fill a single rectangular area or XFillRectangles to fill multiple rectangular areas in the specified drawable. The definition for XFillRectangle is: XFillRectangle(display, d, gc, x, y, width, height) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates are relative to the origin of the drawable and specify the upper left corner of the rectan- gle. width height Specify the width and height. These are the dimensions of the rectangle to be filled. December 18, 1987 - 132 - The definition for XFillRectangles is: XFillRectangles(display, d, gc, rectangles, nrectangles) Display *display; Drawable d; GC gc; XRectangle *rectangles; int nrectangles; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. rectanglesSpecifies a pointer to an array of rectangles. nrectanglesSpecifies the number of rectangles in the array. The XFillRectangle and XFillRectangles functions fill the specified rectangle or rectangles as if a four-point XFillPolygon were specified for each rectangle: [x,y] [x+width,y] [x+width,y+height] [x,y+height] Each function uses the x and y coordinates, width and height dimensions, and graphics context you specify. Both func- tions use these graphics context components: function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The two func- tions also use these graphics context mode_dependent com- ponents: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin. In the case of XFillRectangle, you simply specify a single rectangle to be filled. For XFillRectangles, you specify an array of XRectangle structures, each of which contains a rectangle's x and y coordinates and width and height. XFillRectangles fills the rectangles in the order listed in the array. The x and y coordinates of each rectangle are relative to the drawable's origin and define the upper left corner of the rectangle. For any given rectangle, no pixel is drawn more than once. If rectangles intersect, the inter- secting pixels are drawn multiple times. The errors that can be generated by XFillRectangle and XFillRectangles are BadDrawable, BadGC, and BadMatch. 6.4.2. Filling a Single Polygon Use XFillPolygon to fill a polygon area in the specified drawable. The definition for this function is: December 18, 1987 - 133 - XFillPolygon(display, d, gc, points, npoints, shape, mode) Display *display; Drawable d; GC gc; XPoint *points; int npoints; int shape; int mode; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. points Specifies a pointer to an array of points. npoints Specifies the number of points in the array. shape Specifies an argument that helps the server to improve performance. You can pass one of these constants: Complex, Convex, or Nonconvex. mode Specifies the coordinate mode. CoordModeOrigin treats a coordinates as related to the origin, while CoordModePrevious treates all coordinates after the first as relative to the previous point. The XFillPolygon function uses these graphics context com- ponents when filling the polygon area: function, plane_mask, fill_style, fill_rule, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode_dependent components: foreground, tile, stipple, ts_x_origin, and ts_y_origin. XFillPolygon fills the region closed by the specified path. The path is closed automatically if the last point in the list does not coincide with the first point. No pixel of the region is drawn more than once. XFillPolygon requires a mode argument to determine whether the points are relative to the drawable's origin or to the previous point: o If mode is CoordModeOrigin, all points after the first are relative to the drawable's origin. (The first point is always relative to the drawable's origin.) o If mode is CoordModePrevious, all points after the first are relative to the previous point. XFillPolygon also requires a shape argument: December 18, 1987 - 134 - o If shape is Complex, the path may self-intersect. o If shape is Nonconvex, the path does not self- intersect, but the shape is not wholly convex. If known by the client, specifying Nonconvex instead of Complex may improve performance. If you specify Nonconvex for a self-intersecting path, the graphics results are unde- fined. o If shape is Convex, the path is wholly convex. If known by the client, specifying Convex can improve perfor- mance. If you specify Convex for a path that is not convex, the graphics results are undefined. The fill_rule member of the GC controls the filling behavior of self-intersecting polygons. The errors that can be generated by XFillPolygon are Bad- Drawable, BadGC, BadMatch, and BadValue. 6.4.3. Filling Single and Multiple Arcs Use XFillArc to fill a single arc or XFillArcs to fill mul- tiple arcs in the specified drawable. The definition for XFillArc is: XFillArc(display, d, gc, x, y, width, height, angle1, angle2) Display *display; Drawable d; GC gc; int x, y; unsigned int width, height; int angle1, angle2; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates are relative to the origin of the drawable and specify the upper left corner of the rectan- gle. width height Specify the width and height. These are the major and minor axes of the arc. angle1 Specifies the start of the arc relative to the three-o-clock position from the center, in units of degrees * 64. December 18, 1987 - 135 - angle2 Specifies the path and extent of the arc relative to the start of the arc, in units of degrees * 64. The definition for XFillArcs is: XFillArcs(display, d, gc, arcs, narcs) Display *display; Drawable d; GC gc; XArc *arcs; int narcs; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. arcs Specifies a pointer to an array of arcs. narcs Specifies the number of arcs in the array. For each arc, XFillArc or XFillArcs fills the region closed by the infinitely thin path described by the specified arc and, depending on the arc_mode specified in the graphics context one or two line segments. For ArcChord, the single line segment joining the endpoints of the arc is used. For ArcPieSlice, the two line segments joining the endpoints of the arc with the center point are used. XFillArc and XFillArcs use these graphics context components when filling the arc or arcs: function, plane_mask, fill_style, arc_mode, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The two functions also use these graphics context mode-dependent components: fore- ground, background, tile, stipple, ts_x_origin, and ts_y_origin. In the case of XFillArc, you simply specify a single arc to be filled. For XFillArcs, you specify an array of XArc structures, each of which contains an arc's x and y coordi- nates, width and height, start position, and path and extent. XFillArcs fills the arcs in the order listed in the array. For any given arc, no pixel is drawn more than once. If regions intersect, the intersecting pixels are drawn mul- tiple times. The errors that can be generated by XFillArc and XFillArcs are BadDrawable, BadGC, and BadMatch. December 18, 1987 - 136 - 6.5. Manipulating Fonts Xlib provides functions with which you can manipulate fonts. The following sections discuss how to: o Load and free fonts o Obtain and free font names o Set and return the font search path o Compute character string sizes o Return logical extents o Query character string sizes Fonts and Information about Fonts The X server loads fonts whenever a program requests a new font. Fonts are unloaded when the last font is no longer referenced. There is never more than one copy of a font stored in the server at one time. Fonts are global across all screens in a server. There are several levels one can deal with fonts. Most applications will simply use XLoad- QueryFont to load a font and query the font metrics. Characters in fonts are regarded as masks. Except for image text requests, the only pixels modified are those in which bits are on in the character. This means that it makes sense to draw text using stipples or tiles (for example, many menus gray-out unusable entries). 6.5.1. Loading and Freeing Fonts Xlib provides functions with which you can load fonts, get font information, unload fonts, and free font information. A few font functions use a GContext in order to specify the Graphics context for a font query. Use XLoadFont to load the specified font. The definition for this function is: Font XLoadFont(display, name) Display *display; char *name; display Specifies the connection to the X server. name Specifies the name of the font. This name is a null terminated string. You should use the ISO Latin-1 encoding, and upper/lower case does not matter. December 18, 1987 - 137 - The XLoadFont function loads the specified font and returns its associated font ID. If the function was unsuccessful at loading the specified font, it generates a BadName error. When the font is no longer needed, the client should call XUnloadFont. Fonts are not associated with a particular screen and can be stored as a component of any graphics con- text. The errors that can be generated by XLoadFont are BadAlloc and BadName. Use XGContextFromGC to obtain the GContext for the specified GC. The definition for this function is: GContext XGContextFromGC(gc) GC gc; gc Specifies the graphics context that you want the resource for. Use XQueryFont to return information about a loaded font. The definition for this function is: XFontStruct *XQueryFont(display, font_ID) Display *display; XID font_ID; display Specifies the connection to the X server. font_ID Specifies the ID of the font or the graphics con- text whose current font you want font information about. The XQueryFont function returns a pointer to the XFontStruct structure, which contains information associated with the font. You can either query fonts or the fonts stored in the GC. Use XFreeFontInfo to free this data. In this case, the font ID stored in the XFontstruct will be the ID of the GC, and you need to be careful when using this ID in other func- tions. For example, the ID of the GC is not valid as a font ID in a call to a Set or Get font function. Use XListFontsWithInfo to obtain the names and information about loaded fonts. The definition for this function is: December 18, 1987 - 138 - char **XListFontsWithInfo(display, pattern, maxnames, count_return, info_return) Display *display; char *pattern; int maxnames; int *count_return; XFontStruct **info_return; display Specifies the connection to the X server. pattern Specifies the null-terminated string associated with the font names that you want returned. You can specify any string, an asterisk (*), or a question mark (?). The asterisk indicates a wild- card on any number of characters, and the question mark indicates a wildcard on a single character. maxnames Specifies the maximum number of names that are to be in the returned list. count_returnReturns the actual number of matched font names. info_returnReturns a pointer to the font information. The XListFontsWithInfo function returns a list of names of fonts that match the specified pattern and their associated font information. The list of names is limited to size specified by the maxnames argument. The information returned for each font is identical to what XLoadQueryFont would return, except that the per-character metrics are not returned. To free the allocated name array, the client should call XFreeFontNames. To free the the font informa- tion array, the client should call XFreeFontInfo. Use XFreeFontInfo to free the the font information array. The definition for this function is: XFreeFontInfo(names, free_info, actual_count) char **names; XFontStruct *free_info; int actual_count; names Specifies a pointer to the list of font names that were returned by XListFontsWithInfo. free_info Specifies a pointer to the font information that was returned by XlistFontWithInfo. actual_countSpecifies the actual number of matched font names that were returned by XlistFontsWithInfo. December 18, 1987 - 139 - Use XLoadQueryFont to perform a XLoadFont and XQueryFont in a single operation. The definition for this function is: XFontStruct *XLoadQueryFont(display, name) Display *display; char *name; display Specifies the connection to the X server. name Specifies the name of the font. This name is a null terminated string. The XLoadQueryFont function provides the most common way for accessing a font. That is, XLoadQueryFont both opens (loads) the specified font and returns a pointer to the appropriate XFontStruct structure. If the font does not exist, XLoadQueryFont returns NULL. The XFontStruct structure contains all of the information for the font and consists of the font specific information as well as a pointer to an array of XCharStruct structures for the characters contained in the font. The information in the XFontStruct, XFontProp, and XCharStruct structures is: typedef struct { short lbearing; /* origin to left edge of raster */ short rbearing; /* origin to right edge of raster */ short width; /* advance to next char's origin */ short ascent; /* baseline to top edge of raster */ short descent; /* baseline to bottom edge of raster */ unsigned short attributes;/* per char flags (not predefined) */ } XCharStruct; typedef struct { Atom name; unsigned long card32; } XFontProp; typedef struct { /* normal 16 bit characters are two bytes */ unsigned char byte1; unsigned char byte2; } XChar2b; December 18, 1987 - 140 - typedef struct { XExtData *ext_data; /* hook for extension to hang data */ Font fid; /* Font id for this font */ unsigned direction; /* hint about the direction font is painted */ unsigned min_char_or_byte2;/* first character */ unsigned max_char_or_byte2;/* last character */ unsigned min_byte1; /* first row that exists */ unsigned max_byte1; /* last row that exists */ Bool all_chars_exist;/* flag if all characters have nonzero size*/ unsigned default_char;/* char to print for undefined character */ int n_properties;/* how many properties there are */ XFontProp *properties; /* pointer to array of additional properties*/ XCharStruct min_bounds; /* minimum bounds over all existing char*/ XCharStruct max_bounds; /* maximum bounds over all existing char*/ XCharStruct *per_char; /* first_char to last_char information */ int ascent; /* logical extent above baseline for spacing */ int descent; /* logical decent below baseline for spacing */ } XFontStruct; X supports both single byte/character and two bytes/character text operations. Note that either form can be used with a font, but a single byte/character text requests can only specify a single byte (that is, the first row of a two byte font). You should view two byte fonts as a two dimensional matrix of defined characters: byte1 speci- fies the range of defined rows and byte2 defines the range of defined columns of the font. Single byte/character fonts have no rows defined, and the byte2 range specified in the structure defines a range of characters. The bounding box of a character is defined by the XChar- Struct of that character (see below). However, characters may be absent from a font. In this case, the default font is used. Some fonts may have characters all the same size. In this case, only the information in the XFontStruct char- acters are used. The members of the XFontStruct structure are: o The direction member can be either FontLeftToRight or FontRightToLeft. Essentially, it is just a hint as to whether most XCharStruct elements have a positive ( FontLeftToRight) or a negative ( FontRightToLeft) character-width metric. The core protocol defines no support for vertical text. o If the min_byte1 and max_byte1 members are both zero, min_char_or_byte2 specifies the linear character index corresponding to the first element of the per_char array, and max_char_or_byte2 specifies the linear char- acter index of the last element. December 18, 1987 - 141 - If either min_byte1 or max_byte1 are nonzero, both min_char_or_byte2 and max_char_or_byte2 will be less than 256, and the two-byte character index values corresponding to the per_char array element N (counting from 0) are: byte1 = N/D + min_byte1 byte2 = N\D + min_char_or_byte2 where: D = max_char_or_byte2 - min_char_or_byte2 + 1 / = integer division \ = integer modulus o If the per_char pointer is NULL, all glyphs between the first and last character indexes inclusive have the same information, as given by both min_bounds and max_bounds. o If all_chars_exist is True, all characters in the per_char array have nonzero bounding boxes. o The default_char member specifies the character that will be used when an undefined or nonexistent character is used. The default_char is a 16 bit character (not a two byte character). For a font using two byte matrix format, the default_char has byte1 in the most signifi- cant byte, and byte2 in the least significant byte. If the default_char itself specifies an undefined or nonexistent character, no printing is performed for an undefined or nonexistent character. o The min_bounds and max_bounds members contain the most extreme values of each individual XCharStruct component over all elements of this array (ignores nonexistent characters). The bounding box of the font (the smal- lest rectangle enclosing the shape obtained by superim- posing all of the characters at the same origin [x,y]) has its upper left coordinate at: [x + min_bounds.lbearing, y - max_bounds.ascent] Its width is: max_bounds.rbearing - min_bounds.lbearing Its height is: max_bounds.ascent + max_bounds.descent The x and y are the lower left corner of the box that is relative to the origin. December 18, 1987 - 142 - o The ascent member is the logical extent of the font above the baseline that is used for determining line spacing. Specific characters may extend beyond this. o The descent member is the logical extent of the font at or below the baseline that is used for determining line spacing. Specific characters may extend beyond this. If the baseline is at Y-coordinate y, the logical extent of the font is inclusive between the Y- coordinate values (y-font.ascent) and (y + font.descent - 1). A font is not guaranteed to have any properties. The interpretation of the property value (for example, int32, card32) must be derived from a priori knowledge of the pro- perty. When possible, fonts should have at least the proper- ties listed in the following table. With atom names, upper/lower case matters. The following builtin property atoms can be found in <X11/Xatom.h>. ____________________________________________________________________ Property Name Type Description ____________________________________________________________________ MIN_SPACE unsigned The minimum interword spacing (in pixels). NORM_SPACE unsigned The normal interword spacing (in pixels). MAX_SPACE unsigned The maximum interword spacing (in pixels). END_SPACE unsigned The additional spacing (in pixels) at the end of sentences. SUPERSCRIPT_X int Offset from the character origin where superscripts should begin (in pixels). If the origin is at [x,y], then superscripts should begin at [x + SUPERSCRIPT_X, y - SUPERSCRIPT_Y]. SUPERSCRIPT_Y int Offset from the character origin where superscripts should begin (in pixels). If the origin is at [x,y], then superscripts should begin at [x + SUPERSCRIPT_X, y - SUPERSCRIPT_Y]. SUBSCRIPT_X int Offset from the character origin where subscripts should begin (in pixels). If the origin is at [x,y], then subscripts should begin at December 18, 1987 - 143 - ____________________________________________________________________ Property Name Type Description ____________________________________________________________________ [x + SUPERSCRIPT_X, y + SUPERSCRIPT_Y]. December 18, 1987 - 144 - ____________________________________________________________________ Property Name Type Description ____________________________________________________________________ December 18, 1987 - 145 - ____________________________________________________________________ Property Name Type Description ____________________________________________________________________ SUBSCRIPT_Y int Offset from the character origin where subscripts should begin (in pixels). If the origin is at [x,y], then subscripts should begin at [x + SUPERSCRIPT_X, y + SUPERSCRIPT_Y]. UNDERLINE_POSITION int Y offset from the baseline to the top of an underline (in pixels). If the baseline is Y-coordinate y, then the top of the underline is at (y + UNDERLINE_POSITION). UNDERLINE_THICKNESS unsigned Thickness of the underline (in pix- els) STRIKEOUT_ASCENT int Vertical extents for boxing or voiding characters (in pixels). If the baseline is at Y-coordinate y, then the top of the strikeout box is at (y - STRIKEOUT_ASCENT), and the height of the box is (STRIKEOUT_ASCENT + STRIKEOUT_DESCENT). STRIKEOUT_DESCENT int Vertical extents for boxing or voiding characters (in pixels). If the baseline is at Y-coordinate y, then the top of the strikeout box is at (y - STRIKEOUT_ASCENT), and the height of the box is (STRIKEOUT_ASCENT + STRIKEOUT_DESCENT). ITALIC_ANGLE int The angle of the dominant staffs of characters in the font, in degrees scaled by 64, relative to the three-o-clock position from the character origin, with positive indicating counterclockwise motion (as in the XDrawArc functions). X_HEIGHT int ``1 ex'' as in TeX, but expressed in units of pixels. Often the height of lowercase x. QUAD_WIDTH int ``1 em'' as in TeX, but expressed in units of pixels. Often the width of the digits 0-9. December 18, 1987 - 146 - ____________________________________________________________________ Property Name Type Description ____________________________________________________________________ WEIGHT unsigned The weight or boldness of the font, expressed as a value between 0 and 1000. POINT_SIZE unsigned The point size of this font at the ideal resolution, expressed in 1/10ths of points. There are 72.27 points to the inch. RESOLUTION unsigned The number of pixels per point, expressed in 1/100ths, at which this font was created. CAP_HEIGHT int Y offset from the baseline to the top of the capital letters, ignor- ing accents, in pixels. If the baseline is at Y-coordinate y, then the top of the capitals is at (y - CAP_HEIGHT). ____________________________________________________________________ For a character origin at [x,y], the bounding box of a char- acter (the smallest rectangle, described in terms of XChar- Struct components, enclosing the character's shape) is a rectangle with its upper left corner at: [x + lbearing, y - ascent] Its width is: rbearing - lbearing Its height is: ascent + descent The origin for the next character is defined to be: [x + character-width, y] Note that the baseline is logically viewed as being just below nondescending characters. When descent is zero, only pixels with Y-coordinates less than y are drawn. And, the origin is logically viewed as being coincident with the left edge of a nonkerned character. When lbearing is zero (0), no pixels with X-coordinate less than x are drawn). Any of these values could be negative. The interpretation of the attributes member in the XChar- Struct structure is not defined by the core X protocol. A nonexistent character is represented with all members of December 18, 1987 - 147 - XCharStruct set to zero (0). The error that can be generated by XLoadQueryFont is BadAl- loc. Use XFreeFont to unload the font and free the storage used by the font structure that was allocated by XQueryFont or XLoadQueryFont. The definition for this function is: XFreeFont(display, font_struct) Display *display; XFontStruct *font_struct; display Specifies the connection to the X server. font_structSpecifies the storage associated with the font. The XFreeFont function deletes the association between the font resource ID and the specified font. The font itself will be freed when no other resource references it. The data and the font should not be referenced again. The error that can be generated by XFreeFont is BadFont. Use XGetFontProperty to return the specified font property. The definition for this function is: Bool XGetFontProperty(font_struct, atom, value_return) XFontStruct *font_struct; Atom atom; unsigned long *value_return; font_structSpecifies the storage associated with the font. atom Specifies the atom associated with the string name you want returned. value_returnReturns the value of the font property. Given the atom for that property, the XGetFontProperty func- tion returns the value of the specified font property. The function returns zero (0) if the atom was not defined or one (1) if it was defined. There are a set of predefined atoms for font properties which can be found in <X11/Xatom.h>. This set contains the standard properties associated with a font. While not guaranteed to be present, it it is very likely that the predefined font properties will be present. December 18, 1987 - 148 - Use XUnloadFont to unload the specified font that was loaded by XLoadFont. The definition for this function is: XUnloadFont(display, font) Display *display; Font font; display Specifies the connection to the X server. font Specifies the font ID. The XUnloadFont function deletes the association between the font resource ID and the specified font. The font itself will be freed when no other resource references it. The font may be unloaded on the X server if this is the last refer- ence to the font. In any case, the font should never again be referenced because the resource ID is destroyed. The error that can be generated by XUnloadFont is BadFont. 6.5.2. Obtaining and Freeing Font Names Xlib provides functions with which you can obtain and free font names. Fonts have font names that usually are related or obvious. These functions let you obtain font names by matching a wild card specification by querying a font type for a list of available sizes, and so on. Use XListFonts to return a list of the available font names. The definition for this function is: char **XListFonts(display, pattern, maxnames, actual_count_return) Display *display; char *pattern; int maxnames; int *actual_count_return; display Specifies the connection to the X server. pattern Specifies the null-terminated string associated with the font names that you want returned. You can specify any string, an asterisk (*), or a question mark (?). The asterisk indicates a wild- card on any number of characters, and the question mark indicates a wildcard on a single character. maxnames Specifies the maximum number of names that are to be in the returned list. December 18, 1987 - 149 - actual_count_returnReturns the actual number of font names. The XListFonts function returns an array of font names that match the string you passed to the pattern argument. The string should be ISO Latin-1, and upper/lower case does not matter. Each string is terminated by NULL. The maximum number of names returned in the list depends on the value you passed to the maxnames argument. The function places the actual number of font names returned in the actual_count_return argument. The client should call XFreeFontNames when done with the result to free the memory. Use XFreeFontNames to free a font name array. The defini- tion for this function is: XFreeFontNames(list) char *list[]; list Specifies the array of strings you want to free. The XFreeFontNames function frees the array and strings returned by XListFonts. 6.5.3. Setting and Retrieving the Font Search Path Xlib provides functions with which you can set and retrieve the font search path. Use XSetFontPath to set the font search path. The defini- tion for this function is: XSetFontPath(display, directories, ndirs) Display *display; char **directories; int ndirs; display Specifies the connection to the X server. directoriesSpecifies the directory path used to look for a font. Setting the path to the empty list restores the default path defined for the X server. ndirs Specifies the number of directories in the path. The XSetFontPath function defines the directory search path for font lookup. There is only one search path per X server, not one per client. The interpretation of the strings is operating system dependent, but they are intended to specify directories to be searched in the order listed. Also, the contents of these strings are operating system December 18, 1987 - 150 - specific and are not intended to be used by client applica- tions. Usually, the X server is free to cache font informa- tion internally rather than having to read fonts from files. As a side-effect of executing this function, the X server is guaranteed to flush all cached information about fonts for which there currently are no explicit resource IDs allo- cated. The meaning of an error from this request is system specific. The error that can be generated by XSetFontPath is BadValue. Use XGetFontPath to get the current font search path. The definition for this function is: char **XGetFontPath(display, npaths_return) Display *display; int *npaths_return; display Specifies the connection to the X server. npaths_returnReturns the number of strings in the font path array. The XGetFontPath function allocates and returns an array of strings containing the search path. The data in the font path should be freed when no longer needed. Use XFreeFontPath to free data returned by XGetFontPath. The definition for this function is: XFreeFontPath(list) char **list; list Specifies the array of strings you want to free. The XFreeFontPath function, when presented the data from XGetFontPath, frees the data used by the array. 6.5.4. Computing Character String Sizes Xlib provides functions with which you can compute the width, the logical extents, and server information about 8- bit and 16-bit text strings. Use XTextWidth to determine the width of an 8-bit character string or XTextWidth16 to determine the width of a 16-bit character. Width is computed by adding the character widths December 18, 1987 - 151 - of all of the characters. It does not matter if the font is an 8-bit or 16-bit font. These functions return the sum of the character metrics, in pixels. The definition for XTextWidth is: int XTextWidth(font_struct, string, count) XFontStruct *font_struct; char *string; int count; font_structSpecifies the font used for the width computa- tion. string Specifies the character string. count Specifies the character count in the named string. The definition for XTextWidth16 is: int XTextWidth16(font_struct, string, count) XFontStruct *font_struct; XChar2b *string; int count; font_structSpecifies the font used for the width computa- tion. string Specifies the character string. count Specifies the character count in the named string. 6.5.5. Returning Logical Extents Use XTextExtents to determine the logical extents of the specified 8-bit character string or XTextExtents16 to return the logical extents of the specified 16-bit character string. The logical extents of a string is the width and height of the bounding box occupied by the string in the specified font. The definition for XTextExtents is: XTextExtents(font_struct, string, nchars, direction_return, ascent_return, descent_return, overall_return) XFontStruct *font_struct; char *string; int nchars; int *direction_return; int *ascent_return, *descent_return; XCharStruct *overall_return; December 18, 1987 - 152 - font_structSpecifies a pointer to the XFontStruct structure. string Specifies the character string. nchars Specifies the number of characters in the charac- ter string. direction_returnReturns the value of the direction hint member: FontLeftToRight or FontRightToLeft. ascent_returnReturns the font ascent member. descent_returnReturns the font descent member. overall_returnReturns the overall size in the specified XCharStruct structure. The definition for XTextExtents16 is: XTextExtents16(font_struct, string, nchars, direction_return, ascent_return, descent_return, overall_return) XFontStruct *font_struct; XChar2b *string; int nchars; int *direction_return; int *ascent_return, *descent_return; XCharStruct *overall_return; font_structSpecifies a pointer to the XFontStruct structure. string Specifies the character string. nchars Specifies the number of characters in the charac- ter string. direction_returnReturns the value of the direction hint member: FontLeftToRight or FontRightToLeft. ascent_returnReturns the font ascent member. descent_returnReturns the font descent member. overall_returnReturns the overall size in the specified XCharStruct structure. The XTextExtent and XTextExtents16 functions perform the size computation locally and, thereby, avoid the roundtrip overhead of XQueryTextExtents and XQueryTextExtents16. For the elements returned from the ascent is the maximum of the ascent metrics of all characters in the string. The descent is the maximum of the descent metrics. The width is the sum December 18, 1987 - 153 - of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string. Let R be the right-side-bearing metric of the character plus W. The lbearing member is the minimum L of all characters in the string. The rbearing member is the maximum R. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server interprets each XChar2b as a 16-bit number that has been transmitted with the most signi- ficant byte first. That is, byte1 of the XChar2b is taken as the most significant byte. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics. 6.5.6. Querying Character String Sizes Use XQueryTextExtents to query the server for the sizes of an 8-bit character string or XQueryTextExtents16 to query the server for the sizes of a 16-bit character string. The definition for XQueryTextExtents is: XQueryTextExtents(display, font_ID, string, nchars,direction_return, ascent_return, descent_return, overall_return) Display *display; XID font_ID; char *string; int nchars; int *direction_return; int *ascent_return, *descent_return; XCharStruct *overall_return; display Specifies the connection to the X server. font_ID Specifies either the font ID or the graphics con- text that contains the font. string Specifies the character string. nchars Specifies the number of characters in the charac- ter string. direction_returnReturns the value of the direction hint member: FontLeftToRight or FontRightToLeft. ascent_returnReturns the font ascent member. descent_returnReturns the font descent member. overall_returnReturns the overall size in the specified XCharStruct structure. December 18, 1987 - 154 - The definition for XQueryTextExtents16 is: XQueryTextExtents16(display, font_ID, string, nchars, direction_return, ascent_return, descent_return, overall_return) Display *display; XID font_ID; XChar2b *string; int nchars; int *direction_return; int *ascent_return, *descent_return; XCharStruct *overall_return; display Specifies the connection to the X server. font_ID Specifies either the font ID or the graphics con- text that contains the font. string Specifies the character string. nchars Specifies the number of characters in the charac- ter string. direction_returnReturns the value of the direction hint member: FontLeftToRight or FontRightToLeft. ascent_returnReturns the font ascent member. descent_returnReturns the font descent member. overall_returnReturns the overall size in the specified XCharStruct structure. The XQueryTextExtents and XQueryTextExtents16 functions return the logical extents of the specified 8-bit and 16-bit character string in the specified font or the font contained in the specified GC. These functions query the X server and, therefore, suffer the round trip overhead that is avoided by XTextExtents and XTextExtents16. Both functions return a XCharStruct structure whose members are set to the values discussed in the following paragraphs. The ascent member is set to the maximum of the ascent metrics of all characters in the string. The descent member is set to the maximum of the descent metrics. The width member is set to the sum of the character-width metrics of all characters in the string. For each character in the string, let W be the sum of the character-width metrics of all characters preceding it in the string. Let L be the left-side-bearing metric of the character plus W. Let R be the right-side-bearing metric of the character plus W. The lbearing member is set to the minimum L of all characters in the string. The rbearing member is the maximum R. December 18, 1987 - 155 - Note that the string formal parameter for XQueryTextEx- tents16 is of type XChar2b, rather than of type char as in XQueryTextExtents. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server inter- prets each XChar2b as a 16-bit number that has been transmitted with the most significant byte first. That is, byte1 of the XChar2b is taken as the most significant byte. If the font has no defined default character, undefined characters in the string are taken to have all zero metrics. The errors that can be generated by XQueryTextExtents and XQueryTextExtents16 are BadGC and BadFont. 6.6. Drawing Text Characters Xlib provides functions with which you can draw text charac- ters. This section discusses how to draw: o Complex text o Text characters o Image text characters Text Operations All of the functions discussed in the following subsections make use of fonts. A font is a graphical description of a set of characters that are used to increase efficiency when- ever a set of small, similar sized patterns are repeatedly used. typedef struct { char *chars; /* pointer to string */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* Font to print it in, None don't change */ } XTextItem; typedef struct { XChar2b *chars; /* pointer to two byte characters */ int nchars; /* number of characters */ int delta; /* delta between strings */ Font font; /* font to print it in, None don't change */ } XTextItem16; The fundamental text functions XDrawText and XDrawText16 use these structures. If the font member is None, the font is changed before printing and also is stored in the GC. If an error was generated during text drawing, the font in the GC is undefined. December 18, 1987 - 156 - 6.6.1. Drawing Complex Text Use XDrawText to draw 8-bit polytext characters or XDrawText16 to draw 16-bit polytext characters in the speci- fied drawable. The definition for XDrawText is: XDrawText(display, d, gc, x, y, items, nitems) Display *display; Drawable d; GC gc; int x, y; XTextItem *items; int nitems; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the character (initial character origin) and are relative to the origin of the specified drawable. items Specifies a pointer to an array of text items. nitems Specifies the number of text items in the array. The definition for XDrawText16 is: XDrawText16(display, d, gc, x, y, items, nitems) Display *display; Drawable d; GC gc; int x, y; XTextItem16 *items; int nitems; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the character (the initial character origin), and are relative to the origin of the specified December 18, 1987 - 157 - drawable. items Specifies a pointer to an array of text items. nitems Specifies the number of text items in the array. The XDrawText16 function is like XDrawText, except two-byte or 16-bit characters are used. The XDrawText and XDrawText16 functions use the following elements in the specified GC: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. Both functions also use these graphics context mode- dependent components: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin. Each text item is processed in turn. A font member other than None in an item causes the font to be stored in GC and used for subsequent text. A text element delta specifies an additional change in the position along the x axis before the string is drawn. The delta is always added to the char- acter origin, and is not dependent on any characteristics of the font. Each character image, as defined by the font in the GC, is treated as an additional mask for a fill opera- tion on the drawable. If a text item generates a BadFont error, the previous text items may have been drawn. Note that the chars member of the XTextItem16 structure is of type XChar2b, rather than of type char as it is in the XTextItem structure. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server will interpret each member of the XChar2b structure as a 16-bit number that has been transmitted most significant byte first. In other words, the byte1 member of the XChar2b structure is taken as the most significant byte. The errors that can be generated by XDrawText and XDrawText16 are BadDrawable, BadGC, BadFont, and BadMatch. 6.6.2. Drawing Text Characters Use XDrawString to draw 8-bit text characters or XDraw- String16 to draw 16-bit characters in the specified draw- able. The definition for XDrawString is: XDrawString(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; char *string; int length; December 18, 1987 - 158 - display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the character (initial character origin) and are relative to the origin of the specified drawable. string Specifies the character string. length Specifies the number of characters in the string argument. The definition for XDrawString16 is: XDrawString16(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; XChar2b *string; int length; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the character (the initial character origin), and are relative to the origin of the specified draw- able. string Specifies the character string. length Specifies the number of characters in the string argument. The XDrawString and XDrawString16 functions use these graph- ics context components: function, plane_mask, fill_style, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. Both functions also use these graphics context mode-dependent components: foreground, background, tile, stipple, ts_x_origin, and ts_y_origin. Each character December 18, 1987 - 159 - image, as defined by the font in the GC, is treated as an additional mask for a fill operation on the drawable. The errors that can be generated by XDrawString and XDraw- String16 are BadDrawable, BadGC, BadFont, and BadMatch. 6.6.3. Drawing Image Text Characters Some applications, in particular terminal emulators, need to print image text in which both the foreground and background bits of each character are painted. This avoids annoying flicker on many displays. Use XDrawImageString to draw 8- bit or XDrawImageString16 to draw 16-bit image text charac- ters in the specified drawable. These functions also modify both the foreground and background pixels in the characters. The definition for XDrawImageString is: XDrawImageString(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; char *string; int length; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the image text character (initial character ori- gin) and are relative to the origin of the speci- fied drawable. string Specifies the character string. length Specifies the number of characters in the string argument. The definition for XDrawImageString16 is: XDrawImageString16(display, d, gc, x, y, string, length) Display *display; Drawable d; GC gc; int x, y; XChar2b *string; int length; December 18, 1987 - 160 - display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. x y Specify the x and y coordinates. These coordi- nates define the baseline starting position for the image text character and are relative to the origin of the specified drawable. string Specifies the character string. length Specifies the number of characters in the string argument. The XDrawImageText16 function is like XDrawImageText, except two-byte or 16-bit characters are used. XDrawImageString and XDrawImageString16 use these graphics context com- ponents: plane_mask, foreground, background, font, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. The effect is first to fill a destination rectangle with the background pixel defined in the GC and then to paint the text with the foreground pixel. The upper left corner of the filled rectangle is at: [x + overall->lbearing, y - font_ascent] The width is at: overall->rbearing - overall->lbearing The height is at: font_ascent + font_descent The overall->lbearing, overall->rbearing, font_ascent, and font_descent are as would be returned by XQueryTextExtents using gc and string. The function and fill_style defined in the GC are ignored for these functions. The effective func- tion is GXcopy, and the effective fill_style is FillSolid. Note that the string formal parameter for XDrawImageString16 is of type XChar2b, rather than of type char as in XDrawIm- ageString. For fonts defined with linear indexing rather than two-byte matrix indexing, the X server interprets each XChar2b as a 16-bit number that has been transmitted with the most significant byte first. In other words, the byte1 member of the XChar2b structure is taken as the most signi- ficant byte. The errors that can be generated by XDrawImageString and XDrawImageString16 are BadDrawable, BadGC, and BadMatch. December 18, 1987 - 161 - 6.7. Transferring Images Between Client and Server Xlib provides functions with which you can transfer images between a client and the server. Because the server may require diverse data formats, Xlib provides an image object that fully describes the data in memory and that provides for basic operations on that data. You should reference the data through the image object, not the data directly. How- ever, some implementations of the Xlib library may effi- ciently deal with frequently used data formats by replacing routines in the procedure vector with special case routines. Supported operations include destroying the image, getting a pixel, storing a pixel, extracting a sub image of an image, and adding a constant to an image. Note See Chapter 10 for further information about these utility functions. Chapter 10 also has information about additional library functions used to perform basic operations on an image. All the image manipulation functions discussed in this sec- tion make use of the XImage data structure. The members in the XImage structure are: typedef struct _XImage { int width, height; /* size of image */ int xoffset; /* number of pixels offset in X direction */ int format; /* XYBitmap, XYPixmap, ZPixmap */ char *data; /* pointer to image data */ int byte_order; /* data byte order, LSBFirst, MSBFirst */ int bitmap_unit; /* quant. of scanline 8, 16, 32 */ int bitmap_bit_order; /* LSBFirst, MSBFirst */ int bitmap_pad; /* 8, 16, 32 either XY or ZPixmap */ int depth; /* depth of image */ int bytes_per_line; /* accelerator to next line */ int bits_per_pixel; /* bits per pixel (ZPixmap) */ unsigned long red_mask; /* bits in z arrangement */ unsigned long green_mask; unsigned long blue_mask; char *obdata; /* hook for the object routines to hang on */ struct funcs { /* image manipulation routines */ struct _XImage *(*create_image)(); int (*destroy_image)(); unsigned long (*get_pixel)(); int (*put_pixel)(); struct _XImage *(*sub_image)(); int (*add_pixel)(); } f; } XImage; December 18, 1987 - 162 - The XImage structure describes an image as it exists in the client's memory. The user may request that some of the members (for example, height, width, and xoffset) be changed when the image is sent to the server. That is, the user may send a subset of the image. Other members (for example, byte_order, bitmap_unit, and so forth) are characteristics of both the image and of the server. If these members differ between the image and the server, XPutImage makes the appropriate conversions. If the image is formatted as an XYPixmap, (that is, the format member is set to the constant XYPixmap), the the first byte of the first line of plane n is located at the address (data + (n * height * bytes_per_line)). Use XPutImage to combine an image in memory with a rectangle of a drawable on your display. The definition for this function is: XPutImage(display, d, gc, image, src_x, src_y, dst_x, dst_y, width, height) Display *display; Drawable d; GC gc; XImage *image; int src_x, src_y; int dst_x, dst_y; unsigned int width, height; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. image Specifies the image you want combined with the rectangle. src_x Specifies the offset in X from the left edge of the image defined by the XImage data structure. src_y Specifies the offset in from the top edge of the image defined by the XImage data structure. dst_x dst_y Specify the x and y coordinates. These are the coordinates of the subimage and are relative to the origin of the drawable where the image will be drawn. width height Specify the width and height. These are of the subimage. These arguments define the dimensions of the rectangle. December 18, 1987 - 163 - The XPutImage function combines an image in memory with a rectangle of the specified drawable. The function uses these graphics context components: function, plane_mask, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses the graphics context mode-dependent components foreground and background. If XYBitmap format is used, the depth must be one, and the image must be XYFormat. Otherwise, a BadMatch error is generated. The foreground pixel in the GC defines the source for one bits in the image, and the background pixel defines the source for the zero bits. For XYPixmap and ZPixmap, the depth must match the depth of drawable. Otherwise, a BadMatch error is gen- erated. For XYPixmap, the image must be sent in XYFormat. For ZPixmap, the image must be sent in the ZFormat defined for the given depth. The section of the image defined by the src_x, src_y, width, and height arguments are drawn on the specified part of the drawable. The errors that can be generated by XPutImage are BadDraw- able, BadGC, BadValue, and BadMatch. Use XGetImage to return the contents of a rectangle in the specified drawable on the display. This function is intended specifically for rudimentary hardcopy support. The definition for this function is: XImage *XGetImage(display, d, x, y, width, height, plane_mask, format) Display *display; Drawable d; int x, y; unsigned int width, height; long plane_mask; int format; display Specifies the connection to the X server. d Specifies the drawable. x y Specify the x and y coordinates. These coordi- nates define the upper left corner of the rectan- gle and are relative to the origin of the draw- able. width height Specify the width and height of the subimage. These arguments define the dimensions of the rec- tangle. plane_maskSpecifies the plane mask. December 18, 1987 - 164 - format Specifies the format for the image. You can pass one of these constants: XYPixmap or ZPixmap. The XGetImage function returns the XImage structure. This structure provides you with the contents of the specified rectangle of the drawable in the format you specify. If the format argument is XYPixmap, the function transmits only the bit planes you passed to the plane_mask argument. If the plane_mask argument only requests a subset of the planes of the display, the depth of the returned image will be the number of planes requested. If the format argument is ZPix- map, the function transmits as zero the bits in all planes not specified in the plane_mask argument. The function per- forms no range checking on the values in plane_mask and ignores extraneous bits. XGetImage returns the depth of the image to the depth member of the XImage structure. The depth of the image is as specified when the drawable was created. If the drawable is a pixmap, then the given rectangle must be wholly contained within the pixmap, otherwise the X server will generate a BadMatch error. If the drawable is a window, the window must be mapped, and if there were no inferiors or overlapping windows, the specified rectangle of the window would be fully visible on the screen and wholly contained within the outside edges of the window. Other- wise, a BadMatch error is generated. Note that the borders of the window can be included and read with this request. If the window has a backing-store, the backing-store con- tents are returned for regions of the window that are obscured by noninferior windows. Otherwise, the return con- tents of such obscured regions are undefined. Also unde- fined are the returned contents of visible regions of infe- riors of different depth than the specified window. The errors that can be generated by XGetImage are BadDraw- able, BadValue, and BadMatch. Use XGetSubImage to copy the contents of a rectangle in the specified drawable on the display to the specified location within a pre-existing image structure. The definition for this function is: XImage *XGetSubImage(display, d, x, y, width, height, plane_mask, format, dest_image, dest_x, dest_y) Display *display; Drawable d; int x, y; unsigned int width, height; unsigned long plane_mask; int format; XImage *dest_image; int dest_x, dest_y; December 18, 1987 - 165 - display Specifies the connection to the X server. d Specifies the drawable. x y Specify the x and y coordinates. These coordi- nates define the upper left corner of the rectan- gle and are relative to the origin of the draw- able. width height Specify the width and height of the subimage. These arguments define the dimensions of the rec- tangle. plane_maskSpecifies the plane mask. format Specifies the format for the image. You can pass one of these constants: XYPixmap or ZPixmap. dest_imageSpecify the the destination image. dest_x dest_y Specify the x and y coordinates of the destination rectangle relative to its origin. These coordi- nates specify the upper left corner of the desti- nation rectangle. These coordinates determine where the subimage will be placed within the des- tination image. The XGetSubImage function updates the Image with the speci- fied subimage in the same manner as XGetImage. If the for- mat argument is XYPixmap, the function transmits only the bit planes you passed to the plane_mask argument. If the format argument is ZPixmap, the function transmits as zero the bits in all planes not specified in the plane_mask argu- ment. The function performs no range checking on the values in plane_mask and ignores extraneous bits. XGetSubImage does not update any fields in the destination XImage structure. The depth of the destination XImage structure must be the same as that of the drawable. Other- wise, a BadImage error is generated. If the specified subimage does not fit at the specified location on the des- tination image, the right and bottom edges are clipped. If the drawable is a window, the window must be mapped, and it must be the case that, if there were no inferiors or over- lapping windows, the specified rectangle of the window would be fully visible on the screen. Otherwise, a BadMatch error is generated. If the window has a backing-store, then the backing-store contents are returned for regions of the win- dow that are obscured by noninferior windows. Otherwise, the return contents of such obscured regions are undefined. Also undefined are the returned contents of visible regions December 18, 1987 - 166 - of inferiors of different depth than the specified window. The errors that can be generated by XGetSubImage are Bad- Drawable, BadGC, BadValue, and BadMatch. 6.8. Manipulating Cursors Xlib provides functions with which you can manipulate the cursor. This section discusses how to: o Create a cursor o Change or destroy a cursor o Define the cursor for a window Cursors These functions allow you to load and change cursors associ- ated with windows. Each window can have a different cursor defined for it. Whenever the pointer is in a visible win- dow, it will be set to the cursor defined for that window. If no cursor was defined for that window, the cursor will be the that defined for the parent window. From X's perspective, a cursor consists of a cursor shape, mask, colors for the shape and mask, and ``hot spot''. The cursor pixmap determines the shape of the cursor and must be a depth of one (1). The mask pixmap determines the bits which will be modified by the cursor. The colors determine the colors of the shape and mask. The hot spot defines the point on the cursor which will be reported when a pointer event occurs. There may be and probably are limitations imposed by the hardware on cursors as to size and whether a mask is implemented. XQueryBestCursor can be used to find out what sizes are possible. In the future, it is intended that most standard cursors will be stored as a special font. Client programs refer to cursors by using Cursor resource IDs. 6.8.1. Creating a Cursor Xlib provides functions with which you can create a font, bitmap, or glyph cursor. Use XCreateFontCursor to create a cursor from a standard font. XRecolorCursor defined in the next section can be used to change the color of the cursor to the desired colors. The definition for this function is: #include <X11/cursorfont.h> Cursor XCreateFontCursor(display, shape) Display *display; unsigned int shape; December 18, 1987 - 167 - display Specifies the connection to the X server. shape Specifies the shape in which you want to create the standard cursor. X provides a set of standard cursor shapes in a special font named cursorfont. Applications are encouraged to use this interface for their cursors because the font can be custom- ized for the individual display type. The shape argument specifies which glyph of the standard fonts to use. The hotspot comes from the information stored in the cursor font. The initial colors of a cursor are a black foreground and a white background. See Appendix C for further informa- tion about cursors and their shapes in fonts. The errors that can be generated by XCreateFontCursor are BadAlloc, BadMatch, and BadValue. Use XCreatePixmapCursor to create a cursor from two bitmaps. The definition for this function is: Cursor XCreatePixmapCursor(display, source, mask, foreground_color, background_color, x, y) Display *display; Pixmap source; Pixmap mask; XColor *foreground_color; XColor *background_color; unsigned int x, y; display Specifies the connection to the X server. source Specifies the shape of the source cursor. mask Specifies the source bits of the cursor that are to be displayed. You can pass the constant None. foreground_colorSpecifies the red, green, and blue (RGB) values for the foreground of the source. background_colorSpecifies the red, green, and blue (RGB) values for the background of the source. x y Specify the x and y coordinates. These coordi- nates indicate the hot spot relative to the source's origin and must be a point within the source. Otherwise, a BadMatch error is generated. The XCreatePixmapCursor function creates a cursor and returns the cursor ID associated with it. The foreground and background RGB values must be specified using December 18, 1987 - 168 - foreground_color and background_color, even if the X server only has a StaticGray or GrayScale screen. The foreground color is used for the one bits in the source, and the back- ground color is used for the zero bits. Both source and mask, if specified, must have depth one but can have any root. Otherwise, a BadMatch error is generated. The mask argument defines the shape of the cursor; that is, the one bits in the mask define which source pixels will be displayed, where the mask has zero bits, the corresponding bits of the source pixmap are ignored. If no mask is given, all pixels of the source are displayed. The mask, if present, must be the same size as the pixmap defined by the source argument. Otherwise, a BadMatch error is generated. The components of the cursor may be transformed arbitrarily to meet display limitations. The pixmaps can be freed immediately if no further explicit references to them are to be made. Subsequent drawing in the source or mask pixmap has an undefined effect on the cursor. The X server might or might not make a copy of the pixmap. The other event errors that can be generated by XCreatePix- mapCursor are BadAlloc and BadPixmap. Use XCreateGlyphCursor to create a cursor from font glyphs. This is a fundamental request used by XCreateFontCursor. The definition for XCreateGlyphCursor is: Cursor XCreateGlyphCursor(display, source_font, mask_font, source_char, mask_char, foreground_color, background_color) Display *display; Font source_font, mask_font; unsigned int source_char, mask_char; XColor *foreground_color; XColor *background_color; display Specifies the connection to the X server. source_fontSpecifies the font for the source glyph. mask_font Specifies the font for the mask glyph. You can pass the constant None. source_charSpecifies the character glyph for the source. mask_char Specifies the glyph character for the mask. foreground_colorSpecifies the red, green, and blue (RGB) values for the foreground of the source. December 18, 1987 - 169 - background_colorSpecifies the red, green, and blue (RGB) values for the background of the source. The XCreateGlyphCursor function is similar to XCreatePixmap- Cursor and creates a cursor from font glyphs. For XCreateGlyphCursor, however, the source and mask bitmaps are obtained from the specified font glyphs. The source_char must be a defined glyph in source_font, and, if mask_font is given, mask_char must be a defined glyph in mask_font. Oth- erwise, a BadValue error is generated. The mask_font and character are optional. The origins of the source_char and mask_char (if defined) glyphs are positioned coincidently and define the hotspot. The source_char and mask_char need not have the same bounding box metrics, and there is no res- triction on the placement of the hotspot relative to the bounding boxes. If no mask_char is given, all pixels of the source are displayed. You can free the fonts immediately by calling XFreeFont if no further explicit references to them are to be made. Note that schar and mchar are of type unsigned int, not of type XChar2b. For two-byte matrix fonts, the 16-bit value should be formed with the byte1 member in the most signifi- cant byte and the byte2 member in the least significant byte. The other event errors that can be generated by XCreateGlyphCursor are BadAlloc, BadFont, and BadValue. 6.8.2. Changing and Destroying Cursors Xlib provides functions with which you can change the cursor color, destroy the cursor, and determine the cursor size. Use XRecolorCursor to change the color of the specified cur- sor. The definition for this function is: XRecolorCursor(display, cursor, foreground_color, background_color) Display *display; Cursor cursor; XColor *foreground_color, *background_color; display Specifies the connection to the X server. cursor Specifies the cursor. foreground_colorSpecifies the red, green, and blue (RGB) values for the foreground of the source. background_colorSpecifies the red, green, and blue (RGB) values for the background of the source. December 18, 1987 - 170 - The XRecolorCursor function changes the color of the speci- fied cursor, and, if the cursor is being displayed on a screen, the change is visible immediately. The error that can be generated by XRecolorCursor is BadCur- sor. Use XFreeCursor to free (destroy) the specified cursor. The definition for this function is: XFreeCursor(display, cursor) Display *display; Cursor cursor; display Specifies the connection to the X server. cursor Specifies the cursor. The XFreeCursor function deletes the association between the cursor resource ID and the specified cursor. The cursor storage is freed when no other resource references it. The specified cursor ID should not be referred to again or an error will be generated. The error that can be generated by XFreeCursor is BadCursor. Use XQueryBestCursor to determine useful cursor sizes. The definition for this function is: Status XQueryBestCursor(display, d, width, height, width_return, height_return) Display *display; Drawable d; unsigned int width, height; unsigned int *width_return, *height_return; display Specifies the connection to the X server. d Specifies the drawable. The drawable indicates the desired screen. width height Specify the width and height of the cursor that you want the size information for. width_return height_returnReturns the best width and height (that is, closest to the specified width and height). Some displays allow larger cursors than other displays. XQueryBestCursor provides a way to find out what size December 18, 1987 - 171 - cursors are actually possible on the display. This function returns the largest size that can be displayed. For a cur- sor shape, it returns a bitmap shape acceptable for XCreatePixmapCursor. Applications should be prepared to use smaller cursors on displays which cannot support large ones. The error that can be generated by XQueryBestCursor is Bad- Drawable. 6.8.3. Defining the Cursor Xlib provides functions with which you can define or unde- fine the cursor in a window. Use XDefineCursor to define which cursor will be used in a window. The definition for this function is: XDefineCursor(display, w, cursor) Display *display; Window w; Cursor cursor; display Specifies the connection to the X server. w Specifies the window ID. cursor Specifies the cursor that is to be displayed when the pointer is in the specified window. You can pass None if no cursor is to be displayed. If a cursor is set, it will be used when the pointer is in the window. The errors that can be generated by XDefineCursor are BadWindow, BadAlloc, and BadCursor. Use XUndefineCursor to undefine the mouse cursor in the specified window. The definition for this function is: XUndefineCursor(display, w) Display *display; Window w; display Specifies the connection to the X server. w Specifies the window ID. The XUndefineCursor undoes the effect of a previous XDe- fineCursor for this window. When the mouse is in the win- dow, the parent's cursor will now be used. On the root December 18, 1987 - 172 - window, with no cursor specified, the default cursor is restored. The error that can be generated by XUndefineCursor is BadWindow. December 18, 1987 - 173 - Chapter 7 Window Manager Functions Chapter 7 - Window Manager Functions Once you have connected the display to the X server and want to create a window manager application, you can use the Xlib window manager functions to: o Change the parent of a window o Control the lifetime of a window o Manipulate color maps o Manipulate the pointer o Manipulate the keyboard o Grab the server o Control processing o Manipulate the keyboard encoding o Manipulate the screen saver o Control host access Note The functions in this chapter are most often used by window managers, though it can be difficult to definitively categorize functions as application only or window manager only. It is not expected that these functions will be used by most normal application programs. 7.1. Changing the Parent of a Window Use XReparentWindow to change a window's parent within a single screen. There is no way to move a window between screens. The definition for this function is: XReparentWindow(display, w, parent, x, y) Display *display; Window w; Window parent; int x, y; December 18, 1987 - 174 - display Specifies the connection to the X server. w Specifies the window ID. parent Specifies the parent window ID. x y Specify the x and y coordinates of the position in the new parent window of the specified window. The XReparentWindow function reparents the specified window by inserting it as the child of the specified parent. If the window is mapped, XReparentWindow automatically performs an XUnmapWindow request on the specified window. The func- tion then removes the specified window from its current position in the hierarchy and inserts it as the child of the specified parent. The window is placed on top in the stack- ing order with respect to sibling windows. After reparenting the specified window, XReparentWindow causes the X server to generate a ReparentNotify event. The override_redirect member of the structure returned by this event is set to either True or False. Window manager clients normally should ignore this event if this member is set to True. See Chapter 8 for more information on ReparentNotify event processing. Finally, if the specified window was originally mapped, this function automatically performs a XMapWindow request on it. The X server performs normal exposure processing on formerly obscured windows. The X server might not generate exposure events for regions from the initial XUnmapWindow request that are immediately obscured by the final XMapWindow request. A BadMatch error is generated: o If the new parent window is not on the same screen as the old parent window o If the new parent window is the specified window or an inferior of the specified window o If the specified window has a ParentRelative background and if the new parent window is not the same depth as the specified window. The other error that can be generated by XReparentWindow is BadWindow. 7.2. Controlling the Lifetime of a Window The save-set of a client is a list of other client's windows which, if they are inferiors of one of the client's windows at connection close, should not be destroyed and should be remapped if they are unmapped. To allow an application's December 18, 1987 - 175 - window to survive when a window manager that has reparented a window fails, Xlib provides the save-set functions with which you can change a client's save-set, add a subwindow to a client's save-set, or remove a subwindow from a client's save-set. The functions described in this section are used to control the longevity of subwindows that are normally destroyed when the parent is destroyed. For example, a window manager that wants to add decoration to a window by adding a frame might reparent an application's window. When the frame is des- troyed, the application's window should not be destroyed, but returned to its previous place in the window hierarchy. Windows are removed automatically from the save-set by the X server when they are destroyed. For each window in the client's save-set, if the window is an inferior of a window created by the client, the save-set window is reparented to the closest ancestor such that the save-set window is not an inferior of a window created by the client. If the save-set window is unmapped, a MapWindow request is performed on it. After save-set processing, all windows created by the client are destroyed. For each nonwindow resource created by the client, the appropriate Free request is performed. All colors and color map entries allocated by the client are freed. Use XChangeSaveSet to add or remove a window from the client's save-set. The definition for this function is: XChangeSaveSet(display, w, change_mode) Display *display; Window w; int change_mode; display Specifies the connection to the X server. w_add Specifies the window ID of the window whose chil- dren you want to add to the client's save-set. change_modeSpecifies the mode. You can pass one of the con- stants SetModeInsert or SetModeDelete. If SetMo- deInsert, XChangeSaveSet adds the window to this client's save-set. If SetModeDelete, XChangeSaveSet deletes the window from this client's save-set. Depending on the constant you passed to the change_mode argument, the XChangeSaveSet function either adds or removes a subwindow from the client's save-set. The specified window must have been created by some other client. Otherwise, a BadMatch error is generated. See Section 2.6 for December 18, 1987 - 176 - information on what happens to the save-set during connec- tion close. The X server automatically removes windows from the save-set when they are destroyed. The other event errors that can be generated by XChangeSaveSet are BadWindow, BadMatch, and BadValue. Use XAddToSaveSet to add a window to the client's save-set. The definition for this function is: XAddToSaveSet(display, w_add) Display *display; Window w_add; display Specifies the connection to the X server. w_add Specifies the window ID of the window whose chil- dren you want to add to the client's save-set. The XAddToSaveSet function adds the children of the speci- fied window to the client's save-set. The specified window must have been created by some other client. Otherwise, a BadMatch error is generated. See Section 2.6 for informa- tion on what happens to the save-set during connection close. The X server automatically removes windows from the save-set when they are destroyed. The other event errors that can be generated by XAddTo- SaveSet are BadWindow and BadMatch. Use XRemoveFromSaveSet to remove a window from the client's save-set. The definition for this function is: XRemoveFromSaveSet(display, w_remove) Display *display; Window w_remove; display Specifies the connection to the X server. w_remove Specifies the window ID of the window whose chil- dren you want to remove frem the client's save- set. The XRemoveFromSaveSet function removes the children of the specified window from the client's save-set. The specified window must have been created by some other client. Other- wise, a BadMatch error is generated. See Section 2.6 for information on what happens to the save-set during connec- tion close. The X server automatically removes windows from the save-set when they are destroyed. December 18, 1987 - 177 - The other event errors that can be generated by XRemoveFrom- SaveSet are BadWindow and BadMatch. 7.3. Manipulating Color Maps Xlib provides functions with which you can install a color map, uninstall a color map, and obtain a list of installed color maps. Window manager applications usually install and uninstall color maps, and, thus, these tasks should not be performed by normal client applications. The X server always main- tains a subset of the installed color maps in an ordered list called the ``required list.'' The length of the required list is at most the minimum installed maps speci- fied for the screen when the connection is opened to the server. Initially, only the default color map for a screen is installed, but it is not in the required list. The X server maintains the required list as follows: o If you pass a color map resource ID to the cmap argu- ment, XInstallColormap adds the color map to the top of the list and truncates a color map at the bottom of the list, if necessary, so as not to exceed the maximum length of the list. o If you pass a color map resource ID to the cmap argu- ment and that color map is in the required list, XUnin- stallColormap removes the color map from the required list. A colormap is not added to the required list when it is installed implicitly by the server, and the X server cannot implicitly uninstall a colormap that is in the required list. Use XInstallColormap to install a color map. The definition for this function is: XInstallColormap(display, cmap) Display *display; Colormap cmap; display Specifies the connection to the X server. cmap Specifies the color map ID. The XInstallColormap function installs the specified color map for its associated screen. All windows associated with this color map immediately display with true colors. You associated the windows with this color map when you created them by calling the functions XCreateWindow or XCreateSim- pleWindow. See Chapter 3 for a discussion of how to associ- ate a window with a color map using these functions. December 18, 1987 - 178 - The X server obtains the color map from a required list, which is an ordered list containing a subset of the installed color maps. The X server might implicitly install or uninstall additional color maps. Which other color maps get installed or uninstalled is sever-dependent, except that the required list must remain installed. If the specified color map is not already an installed color map, the X server generates a ColormapNotify event on every window hav- ing the cmap as the color map resource ID. In addition, for every other color map that is installed or uninstalled as a result of a call to this function, the X server generates a ColormapNotify event on every window having that cmap as the color map resource ID. The error that can be generated by XInstallColormap is Bad- Color. Use XUninstallColormap to uninstall a color map. The defini- tion for this function is: XUninstallColormap(display, cmap) Display *display; Colormap cmap; display Specifies the connection to the X server. cmap Specifies the color map ID. The XUninstallColormap function removes the specified color map from the required list for its screen. As a result, the specified cmap might be uninstalled, and the X server might implicitly install or uninstall additional color maps. Which color maps get installed or uninstalled is sever- dependent, except that the required list must remain installed. If the specified color map becomes uninstalled, the X server generates a ColormapNotify event on every window having the cmap as the color map resource ID. In addition, for every other color map that is uninstalled as a result of a call to this function, the X server generates a ColormapNotify event on every window having that cmap as the color map resource ID. The error that can be generated by XUninstallColormap is BadColor. Use XListInstalledColormaps to obtain a list of the currently installed color maps. The definition for this function is: December 18, 1987 - 179 - Colormap *XListInstalledColormaps(display, w, num_return) Display *display; Window w; int *num_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose screen you want to obtain the list of currently installed color maps. num_returnReturns the list of currently installed color maps. The XListInstalledColormaps function returns a list of the currently installed color maps for the screen of the speci- fied window. The order in which the color maps appear in the list is not significant, and there is no explicit indi- cation of the required list. You should free the allocated list by using XFree, when it no longer is needed. (See Sec- tion 2.4 for further information.) The error that can be generated by XListInstalledColormaps is BadWindow. 7.4. Manipulating the Pointer Xlib provides functions with which you can control input from the pointer, which usually is a mouse. Note Window managers most often use these facilities to implement certain styles of user interfaces. Some applications may use these facilities for special purposes. However, most applications will not use these functions. Usually, the X server delivers keyboard and mouse events as soon as they occur to the appropriate client depending upon the window and input focus. The X server provides suffi- cient control over event delivery to allow window managers to support mouse ahead and various other styles of user interface. Many of these depend upon synchronous delivery of events. The delivery of pointer and keyboard events can be controlled independently. When mouse buttons or keyboard keys are grabbed, events will be sent to the grabbing client rather than the normal client who would have received the event. If the keyboard or pointer is in asynchronous mode, further mouse and keyboard events will continue to be processed. If the keyboard or December 18, 1987 - 180 - pointer is in synchronous mode, no further events will be processed until the grabbing client allows them. (See XAl- lowEvents.) The keyboard or pointer is considered frozen during this interval. The triggering event can also be replayed. There are two kinds of grabs: active and passive. An active grab occurs when a single client grabs the keyboard and/or pointer explicitly. (See XGrabPointer and XGrabKey- board.) Clients can also grab a particular keyboard key or pointer button in a window. The grab activates when the key or button is actually pressed, and is called a ``passive grab''. Passive grabs can be very convenient for implement- ing reliable pop-up menus. For example, you can arrange to guarantee that the pop-up will be mapped before the up pointer button event occurs by grabbing a button requesting synchronous behavior. The down event will trigger the grab and freeze further processing of pointer events until you have the chance to map the pop up window. You can then allow further event processing. The up event will then be correctly processed relative to the pop-up window. For many operations, there are functions which take a time argument. The X server includes a time stamp in various events. One special time called CurrentTime represents the current server time. The X server maintains the time when the input focus was last changed and the time of the server itself when the client last performed an active grab (dis- cussed below), when the keyboard was last grabbed, when the pointer was last grabbed, or when a selection was last changed. Your application may be slow reacting to an event. You often need some way to specify that your request not occur if some other application has in the meanwhile taken control of the keyboard, pointer, or selection. By provid- ing the timestamp from the event in the request, you can arrange that the operation not take effect if someone else has in the meanwhile performed an operation. Use XGrabPointer to grab the pointer. The definition for this function is: int XGrabPointer(display, grab_window, owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor, time) Display *display; Window grab_window; Bool owner_events; unsigned int event_mask; int pointer_mode, keyboard_mode; Window confine_to; Cursor cursor; Time time; December 18, 1987 - 181 - display Specifies the connection to the X server. grab_windowSpecifies the window ID of the window relative to which events are reported while it is grabbed. owner_eventsSpecifies if the pointer events are to be reported normally (pass True) or with respect to the grab window if selected by the event mask (pass False). event_maskSpecifies which pointer events are reported to the client. They can be the bitwise inclusive OR of these pointer event mask bits: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWin- dowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeyMapSta- teMask. pointer_modeControls further processing of pointer events. You can pass one of these constants: GrabModeSync or GrabModeAsync. keyboard_modeControls further processing of keyboard events. You can pass one of these constants: GrabModeSync or GrabModeAsync. confine_toSpecifies the window to confine the pointer in or None if it is not to be confined. cursor Specifies the cursor that is to be displayed dur- ing the grab. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XGrabPointer function actively grabs control of the pointer and returns GrabSuccess if the grab was successful. Further pointer events are only reported to the grabbing client. This function overrides any active pointer grab by this client. If owner_events is False, all generated pointer events are reported with respect to grab_window and are only reported if selected by event_mask. If owner_events is True, and if a generated pointer event would normally be reported to this client, it is reported nor- mally. Otherwise, the event is reported with respect to the grab_window and is only reported if selected by event_mask. For either value of owner_events, unreported events are dis- carded. Pointer_mode controls further processing of pointer events, and keyboard_mode controls further processing of main December 18, 1987 - 182 - keyboard events. If the pointer_mode is GrabModeAsync, pointer event processing continues normally. If the pointer is currently frozen by this client, the processing of events for the pointer is resumed. If the pointer_mode is GrabMo- deSync, the the pointer, as seen by client applications, appears to freeze, and no further pointer events are gen- erated by the X server until the grabbing client calls the XAllowEvents function. Actual pointer changes are not lost while the pointer is frozen; they are simply queued for later processing. If the keyboard_mode is GrabModeAsync, keyboard event pro- cessing is unaffected by activation of the grab. If the keyboard_mode is GrabModeSync, the the keyboard, as seen by client applications, appears to freeze, and no further key- board events are generated by the X server until the grab- bing client calls the XAllowEvents function. Actual key- board changes are not lost while the pointer is frozen; they are simply queued for later processing. If a cursor is specified, it is displayed regardless of what window the pointer is in. If no cursor is specified, the normal cursor for that window is displayed when the pointer is in grab_window or one of its subwindows; otherwise, the cursor for grab_window is displayed. If a confine_to window is specified, the pointer will be restricted to stay contained in that window. The confine_to window need have no relationship to the grab_window. If the pointer is not initially in the confine_to window, it is warped automatically to the closest edge just before the grab activates and enter/leave events are generated nor- mally. If the confine_to window is subsequently reconfig- ured, the pointer will be warped automatically as necessary to keep it contained in the window. The time argument allows you to avoid certain circumstances that come up if applications take a long while to respond or if there are long network delays. Consider a situation where you have two applications, both of which normally grab the pointer when clicked on. If both applications specify the timestamp from the event, the second application may successfully grab the pointer, while the first gets an indi- cation the other application grabbed the pointer before its request was processed. XGrabPointer generates EnterNotify and LeaveNotify events. The XGrabPointer function fails and returns: GrabNotViewable If grab_window or confine_to window is not viewable. December 18, 1987 - 183 - December 18, 1987 - 184 - AlreadyGrabbed If the pointer is actively grabbed by some other client. GrabFrozen If the pointer is frozen by an active grab of another client. GrabInvalidTime If the specified time is earlier than the last-pointer-grab time or later than the current X server time. Otherwise, the last-pointer-grab time is set to the specified time and the constant Current- Time is replaced by the current X server time. The errors that can be generated by XGrabPointer are BadWin- dow, BadCursor, and BadValue. Use XGrabButton to grab a mouse button. The definition for this function is: XGrabButton(display, button_grab, modifiers, grab_window, owner_events, event_mask, pointer_mode, keyboard_mode, confine_to, cursor) Display *display; unsigned int button_grab; unsigned int modifiers; Window grab_window; Bool owner_events; unsigned int event_mask; int pointer_mode, keyboard_mode; Window confine_to; Cursor cursor; display Specifies the connection to the X server. button_grabSpecifies the pointer button that is to be grabbed when the specified modifier keys are down. You can pass the constant AnyButton, which is equivalent to issuing the grab request for all possible buttons. modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. You can also pass the constant AnyModifier, which is equivalent to issuing the grab request for all possible modifier combinations (including the com- bination of no modifiers). grab_windowSpecifies the window ID of the window you want to grab. December 18, 1987 - 185 - owner_eventsSpecifies if the pointer events are to be reported normally (pass True) or with respect to the grab window if selected by the event mask (pass False). event_maskSpecifies which pointer events are reported to the client. They can be the bitwise inclusive OR of these pointer event mask bits: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWin- dowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeyMapSta- teMask. pointer_modeControls further processing of pointer events. You can pass one of these constants: GrabModeSync or GrabModeAsync. keyboard_modeControls further processing of keyboard events. You can pass one of these constants: GrabModeSync or GrabModeAsync. confine_toSpecifies the window to confine the pointer in or None if it is not to be confined. cursor Specifies the cursor that is to be displayed dur- ing the grab. The XGrabButton function establishes a passive grab. Conse- quently, in the future: o IF the specified button is pressed when the specified modifier keys are down (and no other buttons or modif- ier keys are down) o AND if grab_window contains the pointer o AND if the confine_to window (if any) is viewable o AND if these constraints are not satisfied for any ancestor o THEN the pointer is actively grabbed, as for XGrab- Pointer, the last-pointer-grab time is set to the time at which the button was pressed (as transmitted in the ButtonPress event), and the ButtonPress events is reported. The interpretation of the remaining arguments is as for XGrabPointer. The active grab is terminated automatically when all buttons are released (independent of the state of the modifier keys). December 18, 1987 - 186 - A modifiers of AnyModifier is equivalent to issuing the grab request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned keycodes. A button of AnyButton is equivalent to issuing the request for all possible buttons. Otherwise, it is not required that the specified button currently be assigned to a physical button. The request fails and the X server generates a BadAccess error if some other client has already issued a XGrabButton with the same button/key combination on the same window. When using AnyModifier or AnyButton, the request fails com- pletely generating an BadAccess error (no grabs are esta- blished) if there is a conflicting grab for any combination. The request has no effect on an active grab. The other event errors that can be generated by XGrabButton are BadWindow, BadCursor, BadAccess, and BadValue. Use XUngrabButton to ungrab a mouse button. The definition for this function is: XUngrabButton(display, button_ungrab, modifiers, ungrab_window) Display *display; unsigned int button_ungrab; unsigned int modifiers; Window ungrab_window; display Specifies the connection to the X server. button_ungrabSpecifies the pointer button that is to be released in combination with the modifier keys. You can pass the constant AnyButton, which is equivalent to issuing the ungrab request for all possible buttons. modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. You can also pass the constant AnyModifier, which is equivalent to issuing the ungrab request for all possible modifier combinations (including the com- bination of no modifiers). ungrab_windowSpecifies the window ID of the window you want to ungrab. The XUngrabButton function releases the passive button/key combination on the specified window if it was grabbed by this client. A modifiers of AnyModifier is equivalent to December 18, 1987 - 187 - issuing the ungrab request for all possible modifier combi- nations, including the combination of no modifiers. A but- ton of AnyButton is equivalent to issuing the request for all possible buttons. This function has no effect on an active grab. The error that can be generated by XUngrabButton is BadWin- dow. Use XUngrabPointer to ungrab the pointer. The definition for this function is: XUngrabPointer(display, time) Display *display; Time time; display Specifies the connection to the X server. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XUngrabPointer function releases the pointer and any queued events, if this client has actively grabbed the pointer from XGrabPointer, XGrabButton, or from a normal button press. The function does not release the pointer if the specified time is earlier than the last-pointer-grab time or is later than the current X server time. It also generates EnterNotify and LeaveNotify events. The X server performs an XUngrabPointer automatically if the event window or confine-to window for an active pointer grab becomes not viewable. Use XChangeActivePointerGrab to change the active pointer. The definition for this function is: XChangeActivePointerGrab(display, event_mask, cursor, time) Display *display; unsigned int event_mask; Cursor cursor; Time time; display Specifies the connection to the X server. event_maskSpecifies which pointer events are reported to the client. They can be the bitwise inclusive OR of these pointer event mask bits: ButtonPressMask, ButtonReleaseMask, EnterWindowMask, LeaveWin- dowMask, PointerMotionMask, PointerMotionHintMask, Button1MotionMask, Button2MotionMask, December 18, 1987 - 188 - Button3MotionMask, Button4MotionMask, Button5MotionMask, ButtonMotionMask, KeyMapSta- teMask. cursor Specifies the cursor. This is the cursor that is displayed. A possible value you can pass is None. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XChangeActivePointerGrab function changes the specified dynamic parameters if the pointer is actively grabbed by the client and if the specified time is no earlier than the last-pointer-grab time and no later than the current X server time. This function has no effect on the passive parameters of a XGrabButton. The event-mask is always aug- mented to include ButtonPress mask and ButtonRelease mask. The interpretation of event_mask and cursor is the same as described in XGrabPointer. The error that can be generated by XChangeActivePointerGrab is BadCursor. 7.5. Manipulating the Keyboard Xlib provides functions with which you can grab or ungrab the keyboard as well as allow events. Use XGrabKeyboard to grab the keyboard. The definition for this function is: int XGrabKeyboard(display, grab_window, owner_events, pointer_mode, keyboard_mode, time) Display *display; Window grab_window; Bool owner_events; int pointer_mode, keyboard_mode; Time time; display Specifies the connection to the X server. grab_windowSpecifies the window ID of the window associated with the keyboard you want to grab. owner_eventsSpecifies a boolean value of either True or False. pointer_modeControls further processing of pointer events. You can pass one of these constants: GrabModeSync or GrabModeAsync. December 18, 1987 - 189 - keyboard_modeControls further processing of keyboard events. You can pass one of these constants: GrabModeSync or GrabModeAsync. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XGrabKeyboard function actively grabs control of the main keyboard and generates FocusIn and FocusOut events. Further key events are reported only to the grabbing client. This function overrides any active keyboard grab by this client. If owner_events is False, all generated key events are reported with respect to grab_window. If owner_events is True, then if a generated key event would normally be reported to this client, it is reported normally; otherwise the event is reported with respect to the grab_window. Both KeyPress and KeyRelease events are always reported, indepen- dent of any event selection made by the client. The pointer_mode argument controls the further processing of pointer events, and the keyboard_mode argument controls the further processing of the keyboard events. o If the keyboard_mode argument is GrabModeAsync, key- board event processing continues normally; if the key- board is currently frozen by this client, then process- ing of keyboard events is resumed. If the keyboard_mode argument is GrabModeSync, the keyboard (as seen by client applications) appears to freeze, and no further keyboard events are generated by the server until the grabbing client issues a releasing XAl- lowEvents call. Actual keyboard changes are not lost while the keyboard is frozen; they are simply queued for later processing. o If pointer_mode is GrabModeAsync, pointer event pro- cessing is unaffected by activation of the grab. If pointer_mode is GrabModeSync, the pointer (as seen by client applications) appears to freeze, and no further pointer events are generated by the server until the grabbing client issues a releasing XAllowEvents call. Actual pointer changes are not lost while the pointer is frozen; they are simply queued for later processing. XGrabKeyboard fails and returns: AlreadyGrabbed If the keyboard is actively grabbed by some other client. GrabNotViewable If grab_window is not viewable. GrabInvalidTime December 18, 1987 - 190 - If the specified time is earlier than the last-keyboard-grab time or later than the current X server time. Otherwise, the last-keyboard-grab time is set to the specified time and CurrentTime is replaced by the current X server time. December 18, 1987 - 191 - GrabFrozen If the keyboard is frozen by an active grab of another client. The errors that can be generated by XGrabKeyboard are BadWindow and BadValue. Use XUngrabKeyboard to ungrab the keyboard. The definition for this function is: XUngrabKeyboard(display, time) Display *display; Time time; display Specifies the connection to the X server. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XUngrabKeyboard function releases the keyboard and any queued events if this client has it actively grabbed from either XGrabKeyboard or XGrabKey. The function does not release the keyboard and any queued events if the specified time is earlier than the last-keyboard-grab time or is later than the current X server time. It also generates FocusIn and FocusOut events. The X server automatically performs an XUngrabKeyboard if the event window for an active keyboard grab becomes not viewable. Use XGrabKey to passively grab a single key of the keyboard key. The definition for this function is: XGrabKey(display, keycode, modifiers, grab_window, owner_events, pointer_mode, keyboard_mode) Display *display; int keycode; unsigned int modifiers; Window grab_window; Bool owner_events; int pointer_mode, keyboard_mode; display Specifies the connection to the X server. keycode Specifies the keycode. This keycode maps to the specific key you want to grab. You can pass either the keycode or the constant AnyKey. December 18, 1987 - 192 - modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. You can also pass the constant AnyModifier, which is equivalent to issuing the grab key request for all possible modifier combinations (including the combination of no modifiers). grab_windowSpecifies the window ID of the window associated with the keys you want to grab. owner_eventsSpecifies a boolean value of either True or False. pointer_modeControls further processing of pointer events. You can pass one of these constants: GrabModeSync or GrabModeAsync. keyboard_modeControls further processing of keyboard events. You can pass one of these constants: GrabModeSync or GrabModeAsync. The XGrabKey function establishes a passive grab on the key- board. Consequently, in the future: o IF the specified key, which itself can be a modifier key, is pressed when the specified modifier keys are down (and no other keys are down), o AND EITHER the grab window is an ancestor of (or is) the focus window OR the grab window is a descendent of the focus window and contains the pointer, o AND these constraints are not satisfied for any ances- tor of grab_window, o THEN the keyboard is actively grabbed, as for XGrabKey- board, the last-keyboard-grab time is set to the time at which the key was pressed (as transmitted in the KeyPress event), and the KeyPress event is reported. The interpretation of the remaining arguments is as for XGrabKeyboard. The active grab is terminated automatically when the specified key has been released (independent of the state of the modifier keys). A modifiers of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). It is not required that all modifiers specified have currently assigned keycodes. A key of AnyKey is equivalent to issuing the request for all possible keycodes. Otherwise, the key must be in the range December 18, 1987 - 193 - specified by min_keycode and max_keycode in the connection setup. Otherwise, a BadValue error is generated. A BadAccess error is generated if some other client has issued a XGrabKey with the same key combination on the same window. When using AnyModifier or AnyKey, the request fails completely and the X server generates a BadAccess error and no grabs are established if there is a conflicting grab for any combination. The errors that can be generated by XGrabKey are BadAccess, BadValue, and BadWindow. Use XUngrabKey to ungrab a key. The definition for this function is: XUngrabKey(display, keycode, modifiers, ungrab_window) Display *display; int keycode; unsigned int modifiers; Window ungrab_window; display Specifies the connection to the X server. keycode Specifies the keycode. This keycode maps to the specific key you want to ungrab. You can pass either the keycode or the constant AnyKey. modifiers Specifies the set of keymasks. This mask is the bitwise inclusive OR of these keymask bits: ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. You can also pass the constant AnyModifier, which is equivalent to issuing the ungrab key request for all possible modifier combinations (including the combination of no modifiers). ungrab_windowSpecifies the window ID of the window associ- ated with the keys you want to ungrab. The XUngrabKey function releases the key combination on the specified window if it was grabbed by this client. This function has no effect on an active grab. A modifiers of AnyModifier is equivalent to issuing the request for all possible modifier combinations (including the combination of no modifiers). A key of AnyKey is equivalent to issuing the request for all possible nonmodifier key codes. The error that can be generated by XUngrabKey is BadWindow. Use XAllowEvents to allow further events to be processed December 18, 1987 - 194 - when the device has been frozen. The definition for this function is: XAllowEvents(display, event_mode, time) Display *display; int event_mode; Time time; display Specifies the connection to the X server. event_modeSpecifies the event mode. You can pass one of these constants: AsyncPointer, SyncPointer, AsyncKeyboard, SyncKeyboard, ReplayPointer, ReplayKeyboard, AsyncBoth, or SyncBoth. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XAllowEvents function releases some queued events if the client has caused a device to freeze. The function has no effect if the specified time is earlier than the last-grab time of the most recent active grab for the client, or if the specified time is later than the current X server time. The following describes the processing that occurs depending on what constant you pass to the event_mode argument: AsyncPointer If the pointer is frozen by the client the pointer event processing continues as usual. If the pointer is frozen twice by the client on behalf of two separate grabs, AsyncPointer thaws for both. AsyncPointer has no effect if the pointer is not frozen by the client, but the pointer need not be grabbed by the client. SyncPointer If the pointer is frozen and actively grabbed by the client, pointer event processing continues normally until the next ButtonPress or ButtonRelease event is reported to the client. At this time, the pointer again appears to freeze. However, if the reported event causes the pointer grab to be released, the pointer does not freeze. Sync- Pointer has no effect if the pointer is not frozen by the client or if the pointer is not grabbed by the client. ReplayPointer If the pointer is actively grabbed by the client and is frozen as the result December 18, 1987 - 195 - of an event having been sent to the client (either from the activation of a XGrabButton or from a previous XAl- lowEvents with mode (SyncPointer, but not from a XGrabPointer), the pointer grab is released and that event is com- pletely reprocessed. This time, how- ever, the function ignores any passive grabs at or above (towards the root) the grab_window of the grab just released. The request has no effect if the pointer is not grabbed by the client or if the pointer is not frozen as the result of an event. AsyncKeyboard If the keyboard is frozen by the client, the keyboard event processing continues as usual. If the keyboard is frozen twice by the client on behalf of two separate grabs, AsyncKeyboard ``thaws'' for both. AsyncKeyboard has no effect if the keyboard is not frozen by the client, but the keyboard need not be grabbed by the client. SyncKeyboard If the keyboard is frozen and actively grabbed by the client, keyboard event processing continues as usual until the next KeyPress or KeyRelease event is reported to the client. At this time, the keyboard again appears to freeze. However, if the reported event causes the keyboard grab to be released, the keyboard does not freeze. SyncKeyboard has no effect if the keyboard is not frozen by the client or if the keyboard is not grabbed by the client. ReplayKeyboard If the keyboard is actively grabbed by the client and is frozen as the result of an event having been sent to the client (either from the activation of a XGrabKey or from a previous XAllowEvents with mode (SyncKeyboard, but not from a XGrabKeyboard), the keyboard grab is released and that event is completely reprocessed. This time, however, the function ignores any passive grabs at or above (towards the root) the grab_window of the grab just released. The request has no effect if the keyboard is not grabbed by the client or if the keyboard is not frozen as the result of an event. December 18, 1987 - 196 - SyncBoth If both pointer and keyboard are frozen by the client, event processing (for both devices) continues normally until the next ButtonPress, ButtonRelease, KeyPress, or KeyRelease event is reported to the client for a grabbed device (button event for the pointer, key event for the keyboard), at which time the devices again appear to freeze. However, if the reported event causes the grab to be released, then the dev- ices do not freeze (but if the other device is still grabbed, then a subse- quent event for it will still cause both devices to freeze). SyncBoth has no effect unless both pointer and keyboard are frozen by the client. If the pointer or keyboard is frozen twice by the client on behalf of two separate grabs, SyncBoth "thaws" for both (but a subsequent freeze for SyncBoth will only freeze each device once). AsyncBoth If the pointer and the keyboard are frozen by the client, event processing (for both devices) continues normally. If a device is frozen twice by the client on behalf of two separate grabs, AsyncBoth "thaws" for both. AsyncBoth has no effect unless both pointer and keyboard are frozen by the client. AsyncPointer, SyncPointer, and ReplayPointer have no effect on the processing of keyboard events. AsyncKeyboard, SyncK- eyboard, and ReplayKeyboard have no effect on the processing of pointer events. It is possible for both a pointer grab and a keyboard grab (by the same or different clients) to be active simultaneously. If a device is frozen on behalf of either grab, no event processing is performed for the dev- ice. It is possible for a single device to be frozen because of both grabs. In this case, the freeze must be released on behalf of both grabs before events can again be processed. The error that can be generated by XAllowEvents is BadValue. 7.6. Grabbing the Server Xlib provides functions with which you can grab and ungrab the server. These functions can be used to control process- ing of output on other connections by the window system server. No processing of requests or close downs on any other connection will occur while the server is grabbed. A client closing its connection automatically ungrabs the December 18, 1987 - 197 - server. Although grabbing the server is highly discouraged, it is sometimes necessary. Use XGrabServer to grab the server. The definition for this function is: XGrabServer(display) Display *display; display Specifies the connection to the X server. The XGrabServer function disables processing of requests and close-downs on all other connections than the one this request arrived on. It is recommended that you not grab the X server any more than is absolutely necessary. Use XUngrabServer to ungrab the server. The definition for this function is: XUngrabServer(display) Display *display; display Specifies the connection to the X server. The XUngrabServer function restarts processing of requests and close-downs on other connections. You should avoid grabbing the server as much as possible. 7.7. Miscellaneous Control Function This section discusses how to: o Control the input focus o Control the pointer o Kill clients 7.7.1. Controlling the Input Focus Xlib provides functions with which you can move the pointer position as well as set and get the input focus. Use XWarpPointer to move the pointer to an arbitrary point on the screen. The definition for this function is: December 18, 1987 - 198 - XWarpPointer(display, src_w, dest_w, src_x, src_y, src_width, src_height, dest_x, dest_y) Display *display; Window src_w, dest_w; int src_x, src_y; unsigned int src_width, src_height; int dest_x, dest_y; display Specifies the connection to the X server. src_w Specifies the window ID of the source window. You can pass the window ID or the constant None. dest_w Specifies the window ID of the destination window. You can pass the window ID or the constant None. src_x src_y Specify the x and y coordinates within the source window. src_width src_heightSpecify the width and height of the source window. dest_x dest_y Specify the x and y coordinates within the desti- nation window. The XWarpPointer function moves the pointer to the coordi- nates specified by the dest_x and dest_y arguments, relative to the destination window's origin. If the destination win- dow is None, the pointer is moved by offsets specified by the dest_x and dest_y coordinates. There is seldom any rea- son for calling this function. The pointer should normally be left to the mouse. If you do use this function, however, it generates events just as if the user had instantaneously moved the pointer from one position to another. Note that you cannot use XWarpPointer to move the pointer outside the confine_to window of an active pointer grab. An attempt to do so will only move the pointer as far as the closest edge of the confine_to window. If the src_w argument is None, the move is independent of the current pointer position. However, if src_w is a win- dow, the move only takes place if the pointer is currently contained in a visible portion of the specified rectangle of the src_w. If dest_w is None, the function moves the pointer by offsets (dest_x, dest_y) relative to the current position of the pointer. If dest_w is a window, the func- tion moves the pointer to (dest_x, dest_y) relative to the origin of dest_w. However, if src_w is not None, the move only takes place if the pointer is currently contained in a visible portion of the specified rectangle of the src_w. December 18, 1987 - 199 - The coordinates passed to src_x and src_y are relative to the source window's origin. If src_height is zero (0), the function replaces it with the current height of the source window minus src_y. If src_width is zero (0), the function replaces it with the current width of the source window minus src_x. The error that can be generated by XWarpPointer is BadWin- dow. Use XSetInputFocus to set the input focus. The definition for this function is: XSetInputFocus(display, focus, revert_to, time) Display *display; Window focus; int revert_to; Time time; display Specifies the connection to the X server. focus Specifies the window ID. This is the window in which you want to set the input focus. You can pass the window ID or one of the constants Poin- terRoot or None. revert_to Specifies which window the input focus reverts to if the window becomes not viewable. You can pass one of these constants: RevertToParent, RevertTo- PointerRoot, or RevertToNone. time Specifies the time. You can pass either a times- tamp, expressed in milliseconds, or the constant CurrentTime. The XSetInputFocus function changes the input focus and the last-focus-change time. The function has no effect if the specified time is earlier than the current last-focus-change time or is later than the current X server time. Otherwise, the last-focus-change time is set to the specified time and the CurrentTime replaced by the current X server time. This function causes the X server to generate FocusIn and Focu- sOut events. Depending on what value you assign to the focus argument, XSetInputFocus executes as follows: o If you assign None to the focus argument, all keyboard events are discarded until you set a new focus window. In this case, the revert_to argument is ignored. December 18, 1987 - 200 - o If you assign a window ID to the focus argument, it becomes the keyboard's focus window. If a generated keyboard event would normally be reported to this win- dow or one of its inferiors, the event is reported nor- mally. Otherwise, the event is reported relative to the focus window. o If you assign PointerRoot to the focus argument, the focus window is dynamically taken to be the root window of whatever screen the pointer is on at each keyboard event. In this case, the revert_to argument is ignored. The specified focus window must be viewable at the time XSetInputFocus is called. Otherwise, a BadMatch error is generated. If the focus window later becomes not viewable, the X server evaluates the revert_to argument to determine the new focus window: o If you assign RevertToParent to the revert_to argument, the focus reverts to the parent (or the closest view- able ancestor), and the new revert_to value is taken to be RevertToNone. o If you assign RevertToPointerRoot or RevertToNone to the revert_to argument, the focus reverts to that value. When the focus reverts, the X server generates FocusIn and FocusOut events, but the last-focus-change time is not affected. The errors that can be generated by XSetInputFocus are BadWindow and BadValue. Use XGetInputFocus to obtain the current input focus. The definition for this function is: XGetInputFocus(display, focus_return, revert_to_return) Display *display; Window *focus_return; int *revert_to_return; display Specifies the connection to the X server. focus_returnReturns the focus window ID, the constant Poin- terRoot, or the constant None. revert_to_returnReturns the current focus state. The func- tion can return one of these constants: RevertTo- Parent, RevertToPointerRoot, or RevertToNone. The XGetInputFocus function returns the focus window ID and the current focus state. December 18, 1987 - 201 - 7.7.2. Controlling the Pointer Xlib provides functions with which you can change the pointer control or can get the current pointer control parameters. Use XChangePointerControl to control the interactive feel of the pointer device. The definition for this function is: XChangePointerControl(display, do_accel, do_threshold, accel_numerator, accel_denominator, threshold) Display *display; Bool do_accel, do_threshold; int accel_numerator, accel_denominator; int threshold; display Specifies the connection to the X server. do_accel Specifies a boolean value that controls whether the values for the accel_numerator or accel_denominator are set. You can pass one of these constants: True or False. do_thresholdSpecifies a boolean value that controls whether the value for the accel_numerator or accel_denominator are set. You can pass one of these constants: True or False. accel_numeratorSpecifies the numerator for the acceleration multiplier. accel_denominatorSpecifies the denominator for the accelera- tion multiplier. threshold Specifies the acceleration threshold. The XChangePointerControl function defines how the pointing device moves. The acceleration, expressed as a fraction, is a multiplier for movement. For example, specifying 3/1 means the pointer moves three times as fast as normal. The frac- tion may be rounded arbitrarily by the X server. Accelera- tion only takes effect if the pointer moves more than thres- hold pixels at once and only applies to the amount beyond the value in the threshold argument. Setting a value to -1 restores the default. The values of the do_accel and do_threshold arguments must be nonzero for the pointer values to be set. Otherwise, the parameters will be unchanged. Negative values generate a BadValue error, as does a zero value for the accel_denominator argument. The error that can be generated by XChangePointerControl is BadValue. December 18, 1987 - 202 - Use XGetPointerControl to get the current parameters set for the pointer. The definition for this function is: XGetPointerControl(display, accel_numerator_return, accel_denominator_return, threshold_return) Display *display; int *accel_numerator_return, *accel_denominator_return; int *threshold_return; display Specifies the connection to the X server. accel_numerator_returnReturns the numerator for the acceleration multiplier. accel_denominator_returnReturns the denominator for the acceleration multiplier. threshold_returnReturns the acceleration threshold. The XGetPointerControl function returns the pointer's current acceleration multiplier and acceleration threshold. 7.7.3. Killing Clients Xlib provides functions with which you can control the life time of resources owned by a client or can cause the connec- tion to a client to be destroyed. Use XSetCloseDownMode to change the close down mode of a client. The definition for this function is: XSetCloseDownMode(display, close_mode) Display *display; int close_mode; display Specifies the connection to the X server. close_modeSpecifies the client close down mode you want to change. You can pass one of these constants: DestroyAll, RetainPermanent, or RetainTemporary. The XSetCloseDownMode defines what will happen to the client's resources at connection close. A connection starts in DestroyAll mode. See the Section 2.6 for information on what happens to the client's resources when the close_mode argument is one of the valid constants. The error that can be generated by XSetCloseDownMode is Bad- Value. December 18, 1987 - 203 - Use XKillClient to destroy a client. The definition for this function is: XKillClient(display, resource) Display *display; XID resource; display Specifies the connection to the X server. resource Specifies any resource associated with the client you want to destroy. You can also pass the con- stant AllTemporary. The XKillClient function forces a close-down of the client that created the resource if a valid resource is specified. If the client has already terminated in either RetainPer- manent or RetainTemporary mode, all of the client's resources are destroyed. If AllTemporary is specified, the resources of all clients that have terminated in RetainTem- porary are destroyed. See Section 2.6 for further informa- tion. The error that can be generated by XKillClient is BadValue. 7.8. Manipulating Keyboard Settings Xlib provides functions with which you can change the key- board control, obtain a list of the auto-repeat keys, turn keyboard auto-repeat on or off, ring the bell, set or obtain the pointer button or keyboard mapping, and obtain a bit vector for the keyboard. This section discusses the user preference options of bell, keyclick, mouse behavior, and so on. The default values for many of these functions are determined by command line argu- ments to the X server, and on UNIX-based systems are typi- cally set in /etc/ttys. Not all implementations will actu- ally be able to control all of these parameters. Use XChangeKeyboardControl to change control from a key- board. The definition for this function is: XChangeKeyboardControl(display, value_mask, values) Display *display; unsigned long value_mask; XKeyboardControl *values; display Specifies the connection to the X server. December 18, 1987 - 204 - value_maskSpecifies one value for each one bit in the mask (least to most significant bit). The values are associated with the set of keys for the previously specified keyboard. values Specifies a pointer to the structure XKeyboardCon- trol. The XChangeKeyboardControl function controls the keyboard characteristics defined by the XKeyboardControl structure. The values argument specifies which values are to be changed. The value_mask contains one value for each one bit in the mask (least to most significant bit). This function operates on a XKeyboardControl structure: /* masks for ChangeKeyboardControl */ #define KBKeyClickPercent (1L<<0) #define KBBellPercent (1L<<1) #define KBBellPitch (1L<<2) #define KBBellDuration (1L<<3) #define KBLed (1L<<4) #define KBLedMode (1L<<5) #define KBKey (1L<<6) #define KBAutoRepeatMode (1L<<7) typedef struct { int key_click_percent; int bell_percent; int bell_pitch; int bell_duration; int led; int led_mode int key; int auto_repeat_mode; /* AutoRepeatModeOff, AutoRepeatModeOn, AutoRepeatModeDefault */ } XKeyboardControl; The following describes each of the members of the XKey- boardControl structure. The key_click_percent member sets the volume for key clicks between 0 (off) and 100 (loud) inclusive, if possible. A setting of -1 restores the default. Other negative values generate a BadValue error. The bell_percent sets the base volume for the bell between 0 (off) and 100 (loud) inclusive, if possible. A setting of -1 restores the default. Other negative values generate a Bad- Value error. The bell_pitch member sets the pitch (speci- fied in Hz) of the bell, if possible. A setting to -1 restores the default. Other negative values generate a Bad- Value error. The bell_duration member sets the duration, specified in milliseconds, of the bell, if possible. A set- ting to -1 restores the default. Other negative values December 18, 1987 - 205 - generate a BadValue error. If both the led_mode and led members are specified, the state of those LEDs are changed, if possible. If only led_mode is specified, the state of all LEDs are changed, if possible. At most 32 LEDs numbered from one are supported. No standard interpretation of LEDs is defined. A BadMatch error is generated if an led is specified without an led_mode. If both the auto_repeat_mode and key members are specified, the auto_repeat_mode of that key is changed, if possible (where LED is the ordinal number of the LED to be changed, not a mask). If only auto_repeat_mode is specified, the glo- bal auto_repeat mode for the entire keyboard is changed, if possible, and does not affect the per_key settings. A Bad- Match error is generated if a key is specified without an auto_repeat_mode. A bell generator connected with the console but not directly on a keyboard is treated as if it were part of the main key- board. The order in which controls are verified and altered is server-dependent. If an error is generated, a subset of the controls may have been altered. The errors that can be generated by XChangeKeyboardControl are BadMatch and BadValue. Use XGetKeyboardControl to obtain the current control values for the keyboard. The definition for this function is: XGetKeyboardControl(display, values_return) Display *display; XKeyboardState *values_return; display Specifies the connection to the X server. values_returnReturns the current keyboard parameter in the specified XKeyboardState structure. The XGetKeyboardControl function returns the current control values for the keyboard to the XKeyboardState structure. The members of this structure are: typedef struct { int key_click_percent; int bell_percent; unsigned int bell_pitch, bell_duration; unsigned long led_mask; int global_auto_repeat; char auto_repeats[32]; } XKeyboardState; December 18, 1987 - 206 - For the LEDs, the least significant bit of led_mask corresponds to LED one, and each one bit in led_mask indi- cates an LED that is lit. The auto_repeats member is a bit vector. Each one bit indicates that auto-repeat is enabled for the corresponding key. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7, with the least significant bit in the byte represent- ing key 8N. The global_auto_repeat member can be set to one of the constants AutoRepeatModeOn or AutoRepeatModeOff. Use XAutoRepeatOn to turn on the keyboard auto-repeat. The definition for this function is: XAutoRepeatOn(display) Display *display; display Specifies the connection to the X server. The XAutoRepeatOn function turns on auto-repeat for the key- board on the specified display. Use XAutoRepeatOff to turn off the keyboard auto-repeat. The definition for this function is: XAutoRepeatOff(display) Display *display; display Specifies the connection to the X server. The XAutoRepeatOff function turns off auto-repeat for the keyboard on the specified display. Use XBell to ring the bell. The definition for this function is: XBell(display, percent) Display *display; int percent; display Specifies the connection to the X server. percent Specifies the base volume for the bell, which can range from -100 to 100 inclusive. The XBell function rings the bell on the keyboard on the specified display, if possible. The specified volume is relative to the base volume for the keyboard. If the value for the percent argument is not in the range -100 to 100 December 18, 1987 - 207 - inclusive, a BadValue error is generated. The volume at which the bell is rung when the percent argument is nonnega- tive is: base - [(base * percent) / 100] + percent The volume at which the bell is rung when the percent argu- ment is negative is: base + [(base * percent) / 100] To change the base volume of the bell for this keyboard, use XChangeKeyboardControl. Use XSetPointerMapping to set the mapping of buttons on the pointer. The definition for this function is: int XSetPointerMapping(display, map, nmap) Display *display; unsigned char map[]; int nmap; display Specifies the connection to the X server. map Specifies the mapping list. nmap Specifies the number of items in mapping list. The XSetPointerMapping function sets the mapping of the pointer and causes the X server to generate a MappingNotify event on a status of MappingSuccess. Elements of the list are indexed starting from one. The length of the list must be the same as XGetPointerMapping would return. Otherwise, a BadValue error is generated. The index is a core button number, and the element of the list defines the effective number. A zero element disables a button, and elements are not restricted in value by the number of physical buttons. However, no two elements can have the same nonzero value. Otherwise, a BadValue error is generated. If any of the buttons to be altered are currently in the down state, the status reply is MappingBusy and the mapping is not changed. This function returns either MappingSuccess or MappingBusy. Use XGetPointerMapping to get the pointer mapping. The definition for this function is: int XGetPointerMapping(display, map, nmap) Display *display; unsigned char map[]; int nmap; December 18, 1987 - 208 - display Specifies the connection to the X server. map Specifies the mapping list. nmap Specifies the number of items in mapping list. The XGetPointerMapping function returns the current mapping of the pointer. Elements of the list are indexed starting from one. The length of the list indicates the number of physical buttons. The nominal mapping for a pointer is the identity mapping: map[i]=i. Use XQueryKeymap to obtain a bit vector for the keyboard. The definition for this function is: XQueryKeymap(display, keys_return) Display *display; char keys_return[32]; display Specifies the connection to the X server. keys_returnReturns an array of bytes that identifies which keys are pressed down. Each bit represents one key of the keyboard. The XQueryKeymap function returns a bit vector for the key- board, where each one bit indicates that the corresponding key is currently pressed down. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the least significant bit in the byte representing key 8N. 7.9. Manipulating the Keyboard Encoding A KeyCode represents a physical (or logical) key. Keycodes lie in the inclusive range [8,255]. A keycode value carries no intrinsic information, although server implementors may attempt to encode geometry (for example, matrix) information in some fashion so that it can be interpreted in a server- dependent fashion. The mapping between keys and keycodes cannot be changed. A KeySym is an encoding of a symbol on the cap of a key. The set of defined KeySyms include the ISO Latin character sets (1-4), Katakana, Arabic, Cyrillic, Greek, Technical, Spe- cial, Publishing, APL, Hebrew, and a special miscellany of keys found on keyboards (RETURN, HELP, TAB, and so on). To the extent possible, these sets are derived from interna- tional standards. In areas where no standards exist, some of these sets are derived from Digital standards. The list of December 18, 1987 - 209 - defined symbols can be found in the <X11/keysymdef.h> header file. Unfortunately, some C preprocessors have limits on the number of defined symbols. If you must use keysyms not in the Latin 1-4, Greek, and miscellany classes, you may have to define a symbol for those sets. Most applications usually only include <X11/keysym.h>, which defines symbols for ISO Latin 1-4, Greek, and Miscellany. A list of KeySyms is associated with each KeyCode. The length of the list can vary with each KeyCode. The list is intended to convey the set of symbols on the corresponding key. By convention, if the list contains a single KeySym and if that KeySym is alphabetic and case distinction is relevant for it, then it should be treated as equivalent to a two-element list of the lowercase and uppercase KeySyms. For example, if the list contains the single KeySym for uppercase A, the client should treat it as if it were a pair with lowercase a as the first KeySym and uppercase A as the second KeySym. For any KeyCode, the first KeySym in the list should be chosen as the interpretation of a KeyPress when no modifier keys are down. The second KeySym in the list normally should be chosen when the Shift modifier is on, or when the Lock modifier is on and Lock is interpreted as ShiftLock. When the Lock modifier is on and is interpreted as CapsLock, it is suggested that the Shift modifier first be applied to choose a KeySym, but if that KeySym is lowercase alphabetic, the corresponding uppercase KeySym should be used instead. Other interpretations of CapsLock are possible; for example, it may be viewed as equivalent to ShiftLock, but only apply- ing when the first KeySym is lowercase alphabetic and the second KeySym is the corresponding uppercase alphabetic. No interpretation of KeySyms beyond the first two in a list is suggested here. No spatial geometry of the symbols on the key is defined by their order in the KeySym list, although a geometry might be defined on a vendor-specific basis. The X server does not use the mapping between KeyCodes and KeySyms. Rather, it stores it merely for reading and writ- ing by clients. Note The simple interface, XLookupString will perform simple translation of a key event to an ASCII string. Keyboard related utilities are discussed in Chapter 10. Use XGetKeyboardMapping to obtain the symbols for the speci- fied number of keycodes. The definition for this function is: December 18, 1987 - 210 - KeySym *XGetKeyboardMapping(display, first_keycode_wanted, keycode_count, keysyms_per_keycode_return) Display *display; KeyCode first_keycode_wanted; int keycode_count; int *keysyms_per_keycode_return; display Specifies the connection to the X server. first_keycode_wantedSpecifies the first keycode that is to be returned. keycode_countSpecifies the number of keycodes that are to be returned. keysyms_per_keycode_returnReturns the number of keysyms per keycode. The XGetKeyboardMapping function, starting with first_keycode, returns the symbols for the specified number of keycodes. The value specified in the first_keycode argu- ment must be greater than or equal to min_keycode as returned in the Display structure at connection setup. Oth- erwise, a BadValue error is generated. In addition, the following expression must be less than or equal to max_keycode as returned in the Display structure at connec- tion setup. If this is not the case, a BadValue error is generated. first_keycode + keycode_count - 1 The number of elements in the keysyms list is: keycode_count * keysyms_per_keycode_return Then, KeySym number N, counting from zero, for keycode K has an index, counting from zero, of the following in KeySym: (K - first_code) * keysyms_per_code + N The keysyms_per_keycode_return value is chosen arbitrarily by the X server to be large enough to report all requested symbols. A special KeySym value of NoSymbol is used to fill in unused elements for individual keycodes. Use XFree to free the storage returned by XGetKeyboardMap- ping. (See Section 2.4 for further information.) The other error that can be generated by XGetKeyboardMapping is BadValue. December 18, 1987 - 211 - Use XChangeKeyboardMapping to change the keyboard mapping. The definition for this function is: XChangeKeyboardMapping(display, first_keycode, keysyms_per_keycode, keysyms, num_codes) Display *display; int first_keycode; int keysyms_per_keycode; KeySym *keysyms; int num_codes; display Specifies the connection to the X server. first_keycodeSpecifies the first keycode that is to be changed. keysyms_per_keycodeSpecifies the keysyms that are to be used. keysyms Specifies a pointer to an array of keysyms. num_codes Specifies the number of keycodes that are to be changed. The XChangeKeyboardMapping function, starting with first_keycode, defines the symbols for the specified number of keycodes. The symbols for keycodes outside this range remained unchanged. The number of elements in the keysyms list must be a multiple of keysyms_per_keycode. Otherwise, a BadLength error is generated. The specified first_keycode must be greater than or equal to min_keycode supplied at connection setup and stored in the Display structure. Oth- erwise, a BadValue error is generated. In addition, the following expression must be less than or equal to max_keycode as returned in the connection setup (else a Bad- Value error). first_keycode + (num_codes / keysyms_per_keycode) - 1 The KeySym number N, counting from zero, for keycode K has an index, counting from zero, of the following in keysyms: (K - first_keycode) * keysyms_per_keycode + N The specified keysyms_per_keycode can be chosen arbitrarily by the client to be large enough to hold all desired sym- bols. A special KeySym value of NoSymbol should be used to fill in unused elements for individual keycodes. It is legal for NoSymbol to appear in nontrailing positions of the effective list for a keycode. XChangeKeyboardMapping gen- erates a MappingNotify event. December 18, 1987 - 212 - There is no requirement that the X server interpret this mapping. It is merely stored for reading and writing by clients. The other event errors that can be generated by XChangeKey- boardMapping are BadValue and BadAlloc. The next two functions make use of the following data struc- ture. typedef struct { int max_keypermod; /* This server's max number of keys per modifier */ KeyCode *modifiermap; /* An 8 by max_keypermod array of the modifiers */ } XModifierKeymap; Use XNewModifierMapping to create one of these structures. The definition for this function is: XModifierKeymap XNewModifierMapping(max_keys_per_mod) int max_keys_per_mod; max_keys_per_modSpecifies the maximum number of keycodes assigned to any of the modifiers in the map. The XNewModifierMapping function returns a XModifierKeymap structure. Use XFreeModifierMapping to destroy one of these structures. The definition for this function is: XFreeModifierMapping(modmap) XModifierMapping *modmap; modmap Specifies a pointer to the XModifierKeymap struc- ture. The XFreeModifierMapping function frees the specified XModi- fierKeymap structure. Use XSetModifierMapping to set which keycodes are to be used as modifiers. The definition for this function is: int XSetModifierMapping(display, modmap) Display *display; XModifierKeymap *modmap; display Specifies the connection to the X server. December 18, 1987 - 213 - modmap Specifies a pointer to the XModifierKeymap struc- ture. The XSetModifierMapping function specifies the keycodes of the keys, if any, that are to be used as modifiers. A zero value means that no key should be used. No two arguments can have the same nonzero keycode value. Otherwise, a BadValue error is generated. There are eight modifiers, and the modifiermap member of the XModifierKeymap structure contains eight sets of max_keypermod keycodes, one for each modifier in the order Shift, Lock, Control, Mod1, Mod2, Mod3, Mod4, and Mod5. Only nonzero keycodes have meaning in each set, and nonzero keycodes are ignored. In addition, all of the nonzero key- codes must be in the range specified by min_keycode and max_keycode in the Display structure. Otherwise, a BadValue error is generated. No keycode may appear twice in the entire map. Otherwise, a BadValue error is generated. A X server can impose restrictions on how modifiers can be changed, for example, if certain keys do not generate up transitions in hardware or if multiple modifier keys are not supported. If some such restriction is violated, the status reply is MappingFailed, and none of the modifiers are changed. If the new keycodes specified for a modifier differ from those currently defined and any (current or new) keys for that modifier are in the down state, the status reply is MappingBusy, and none of the modifiers are changed. XSetModifierMapping generates a MappingNotify event on a MappingSuccess status. The other event errors that can be generated by XSetModifi- erMapping are BadAlloc and BadValue. Use XGetModifierMapping to obtain the keycodes that are to be used as modifiers. The definition for this function is: XModifierKeymap *XGetModifierMapping(display) Display *display; display Specifies the connection to the X server. The XGetModifierMapping function returns a newly created XModifierKeymap structure that contains the keys being used as modifiers. The structure should be freed after use with XFreeModifierMapping. If only zero values appear in the set for any modifier, that modifier is disabled. December 18, 1987 - 214 - 7.10. Manipulating the Screen Saver Xlib provides functions with which you can set, force, activate, or reset the screen saver as well as obtain the current screen saver values. Use XSetScreenSaver to set the screen saver. The definition for this function is: XSetScreenSaver(display, timeout, interval, prefer_blanking, allow_exposures) Display *display; int timeout, interval; int prefer_blanking; int allow_exposures; display Specifies the connection to the X server. timeout Specifies the timeout, in seconds, until the screen saver turns on. interval Specifies the interval between screen saver invo- cations. prefer_blankingSpecifies whether to enable screen blanking. Possible values are DontPreferBlanking, Prefer- Blanking, or DefaultBlanking. allow_exposuresSpecifies the current screen save control values. Possible values are DontAllowExposures, AllowExposures, or DefaultExposures. Timeout and interval are specified in seconds. A timeout of 0 disables the screen saver, while a timeout of -1 restores the default. Other negative values generate a BadValue error. If the timeout value is nonzero, the function enables the screen saver. An interval of 0 disables the random pattern motion. If no input from devices (keyboard, mouse, and so on) is generated once the screen saver is enabled, for the specified number of timeout seconds, the screen saver is activated. For each screen, if blanking is preferred and the hardware supports video blanking, the screen will simply go blank. Otherwise, if either exposures are allowed or the screen can be regenerated without sending exposure events to clients, the screen is tiled with the root window background tile at randomly re-origined each interval minutes. Otherwise, the state of the screens do not change, and the screen saver is not activated. The screen saver is deactivated and all screen states are restored at the next keyboard or pointer input or at the next call to XForceScreenSaver with mode ScreenSaverReset. December 18, 1987 - 215 - If the server-dependent screen saver method supports periodic change, the interval argument serves as a hint about how long the change period should be, and zero hints that no periodic change should be made. Examples of ways to change the screen include scrambling the color map periodi- cally, moving an icon image about the screen periodically, or tiling the screen with the root window background tile, randomly reoriginated periodically. The other error that can be generated by XSetScreenSaver is BadValue. Use XForceScreenSaver to force the screen saver. The defini- tion for this function is: XForceScreenSaver(display, mode) Display *display; int mode; display Specifies the connection to the X server. mode Specifies the mode that is to be applied. XFor- ceScreenSaver applies the specified mode to the screen saver. The possible modes are Screen- SaverActive or ScreenSaverReset. If the specified mode is ScreenSaverActive and the screen saver currently is deactivated, the screen saver is activated, even if the screen saver had been disabled with a timeout of zero (0). If the specified mode is ScreenSaver- Reset and the screen saver currently is enabled, the screen saver is deactivated (if it was activated), and the activa- tion timer is reset to its initial state (as if device input had been received). The error that can be generated by XForceScreenSaver is Bad- Value. Use XActivateScreenSaver to activate the screen saver. The definition for this function is: XActivateScreenSaver(display) Display *display; display Specifies the connection to the X server. Use XResetScreenSaver to reset the screen saver. The defini- tion for this function is: December 18, 1987 - 216 - XResetScreenSaver(display) Display *display; display Specifies the connection to the X server. Use XGetScreenSaver to get the current screen saver values. The definition for this function is: XGetScreenSaver(display, timeout_return, interval_return, prefer_blanking_return, allow_exposures_return) Display *display; int *timeout_return, *interval_return; int *prefer_blanking_return; int *allow_exposures_return; display Specifies the connection to the X server. timeout_returnReturns the timeout, in minutes, until the screen saver turns on. interval_returnReturns the interval between screen saver invocations. prefer_blanking_returnReturns the current screen blanking preference: DontPreferBlanking, PreferBlanking, or DefaultBlanking. allow_exposures_returnReturns the current screen save con- trol value: DontAllowExposures, AllowExposures, or DefaultExposures. 7.11. Controlling Host Access Xlib provides functions with which you can control host access. This section discusses how to: o Add, get, or remove hosts from the access control list o Change, enable, or disable access X does not provide any protection on a per-window basis. If you find out the resource ID of a resource, you can manipu- late it. To provide some minimal level of protection, how- ever, connections are only permitted from machines you trust. This is adequate on single user workstations, but obviously breaks down on timesharing machines. While provi- sions exist in the X protocol for proper connection authen- tication, the lack of a standard authentication server leaves us with only host level access control. Currently, you can use both DECnet and TCP domains. December 18, 1987 - 217 - The initial set of hosts allowed to open connections con- sists of: o The host the window system is running on. o On UNIX-based systems, each host is listed in the /etc/X?.hosts file. The `?' indicates the number of the display. This file should consist of host names separated by newlines. DECnet nodes must terminate in ``::'' to distinguish them from internet hosts. If a host is not in the access control list when the access control mechanism is enabled and if the host attempts to establish a connection, the server refuses the connection list or to change the access list. The client must reside on the same host as the server and/or must have been granted permission in the initial authorization at connection setup. The initial access control list can be specified by provid- ing a file that the server can read at startup and reset time. Note Servers also can implement other access control policies in addition to or in place of this hosts access facility. The name and format of the information in this file is operating system specific. For further information about other access control implementations, see X Window Sys- tem Protocol, Version 11. 7.11.1. Adding, Getting, or Removing Hosts Xlib provides functions with which you can add, get, or remove hosts. All the host access control functions use the XHostAddress structure. The elements in this structure are: typedef struct { int family; /* for example AF_DNET */ int length; /* length of address, in bytes */ char *address; /* pointer to where to find the bytes */ } XHostAddress; family Specifies which protocol address family to use (for example, TCP/IP or DECnet). The family sym- bols are defined in <X11/X.h>. length Specifies the length of the address in bytes. address Specifies a pointer to the address. December 18, 1987 - 218 - Use XAddHost to add a single host. The definition for this function is: XAddHost(display, host) Display *display; XHostAddress *host; display Specifies the connection to the X server. host Specifies the network address of the host machine. The XAddHost function adds the specified host to the access control list for that display. The display hardware must be on the same host as the program issuing the command. The errors that can be generated by XAddHost are BadAlloc and BadValue. Use XAddHosts to add multiple hosts at one time. The defini- tion for this function is: XAddHosts(display, hosts, num_hosts) Display *display; XHostAddress *hosts; int num_hosts; display Specifies the connection to the X server. hosts Specifies each host that is to be added. num_hosts Specifies the number of hosts. The XAddHosts function adds each specified host to the access control list for that display. The display hardware must be on the same host as the program issuing the command. The errors that can be generated by XAddHosts are BadAlloc and BadValue. Use XListHosts to obtain a host list. The definition for this function is: XHostAddress *XListHosts(display, nhosts_return, state_return) Display *display; int *nhosts_return; Bool *state_return; December 18, 1987 - 219 - display Specifies the connection to the X server. nhosts_returnReturns the number of hosts currently in the access control list. state_returnReturns the state of the access control (enabled or disabled). The XListHosts function returns the current access control list as well as whether the use of the list at connection setup was enabled or disabled. XListHosts allows a program to find out what machines can make connections. It also returns a pointer to a list of host structures that were allocated by the routine. When it no longer is needed, this memory should be freed by calling XFree. (See Section 2.4 for further information.) Use XRemoveHost to remove a single host. The definition for this function is: XRemoveHost(display, host) Display *display; XHostAddress *host; display Specifies the connection to the X server. host Specifies the network address of the host machine. The XRemoveHost function removes the specified host from the access control list for that display. The display hardware must be on the same host as the client process. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed short of resetting the server. The errors that can be generated by XRemoveHost are BadAlloc and BadValue. Use XRemoveHosts to remove multiple hosts at one time. The definition for this function is: XRemoveHosts(display, hosts, num_hosts) Display *display; XHostAddress *hosts; int num_hosts; display Specifies the connection to the X server. December 18, 1987 - 220 - hosts Specifies each host that is to be added. num_hosts Specifies the number of hosts. The XRemoveHosts function removes each specified host from the access control list for that display. The display hardware must be on the same host as the client process. The XRemoveHosts function removes each specified host from the access control list for that display. The display hardware must be on the same host as the client process. If you remove your machine from the access list, you can no longer connect to that server, and this operation cannot be reversed short of resetting the server. The errors that can be generated by XRemoveHosts are BadAl- loc and BadValue. 7.11.2. Changing, Enabling, or Disabling Access Control Xlib provides functions with which you can enable, disable, or change access control. For these functions to execute successfully, the client application must reside on the same host as the X server, and/or have been given permission in the initial authoriza- tion at connection setup. Use XSetAccessControl to change access control. The defini- tion for this function is: XSetAccessControl(display, mode) Display *display; int mode; display Specifies the connection to the X server. mode Specifies whether you want to change the access control to enable or disable. EnableAccess enables host access control or DisableAccess dis- ables host access control. The XSetAccessControl function either enables or disables the use of the access control list at connection setups. The errors that can be generated by XSetAccessControl are BadAlloc and BadAccess. Use XEnableAccessControl to enable access control. The definition for this function is: December 18, 1987 - 221 - XEnableAccessControl(display) Display *display; display Specifies the connection to the X server. The XEnableAccessControl function enables the use of the access control list at connection setups. The error that can be generated by XEnableAccessControl is BadAccess. Use XDisableAccessControl to disable access control. The definition for this function is: XDisableAccessControl(display) Display *display; display Specifies the connection to the X server. The XDisableAccessControl function disables the use of the access control list at connection setups. The error that can be generated by XDisableAccessControl is BadAccess. December 18, 1987 - 222 - Chapter 8 Events and Event-Handling Functions Chapter 8 - Events and Event-Handling Functions A client application communicates with the X server through the con- nection you establish with the XOpenDisplay function. It is over this connection that a client application sends ``requests'' to the X server. These requests are made by the Xlib functions that are called in the client applica- tion. The X server sends back to the client application either ``replies'' or events. Most requests made by Xlib functions do not generate replies. Some requests generate multiple replies. Numerous Xlib functions cause the X server to generate events. In addition, the user's typing or moving the pointer can generate events asynchronously. This chapter begins with a discussion of the following topics associated with events: o Event types o Event structures o Event mask o Event processing The chapter continues with a discussion of the Xlib func- tions you can use to: o Select events o Handle the output buffer and the event queue o Select events from the event queue o Send and get events o Handle error events Note Some toolkits use their own event-handling rou- tines. Also, some toolkits do not allow you to interchange these event-handling routines with those in the Xlib library. See the document sup- plied with your toolkit for further information. December 18, 1987 - 223 - Most applications simply are event loops. That is, they wait for an event, decide what to do with it, execute some amount of code, which, in turn, results in changes to the display, and then wait for the next event. 8.1. Event Types An event is data generated asynchronously by the X server as a result of some device activity, or as side effects of a request sent by an Xlib function. Device-related events propagate from the source window to ancestor windows until some client application has selected that event type, or until the event is explicitly discarded. The X server never sends an event to a client application, unless the client has specifically asked to be informed of that event type, usually by calling the Xlib function XSelectInput. The mask can also be set when you create a window or by changing the window's event_mask. You can also mask out events that would propagate to outer windows by manipulating the do_not_propagate mask of the window's attributes. The event type describes a specific event generated by the X server. For each event type, there is a corresponding con- stant name defined in <X11/X.h>. When referring to an event type, this manual uses the constant name defined in this file. It is often useful to group one or more event types into logical categories. For example, exposure processing refers to the processing that occurs for the exposure events Expose, GraphicsExpose, and NoExpose. The following table lists the event category and its associ- ated event type or types. The processing associated with these events is discussed in Section 8.4. _________________________________________________________________ Event Category Event Type _________________________________________________________________ Keyboard events KeyPress, KeyRelease Pointer motion events ButtonPress, ButtonRelease, Motion- Notify Window crossing events EnterNotify, LeaveNotify Input focus events FocusIn, FocusOut Key map state notification event KeymapNotify Exposure events Expose, GraphicsExpose, NoExpose Structure control events CirculateRequest, ConfigureRequest, MapRequest, ResizeRequest Window state notification December 18, 1987 - 224 - _________________________________________________________________ Event Category Event Type _________________________________________________________________ events CirculateNotify, ConfigureNotify, December 18, 1987 - 225 - _________________________________________________________________ Event Category Event Type _________________________________________________________________ CreateNotify, DestroyNotify, Gravi- tyNotify, MapNotify, MappingNotify, ReparentNotify, UnmapNotify, Visi- bilityNotify December 18, 1987 - 226 - _________________________________________________________________ Event Category Event Type _________________________________________________________________ December 18, 1987 - 227 - _________________________________________________________________ Event Category Event Type _________________________________________________________________ Color map state notifica- tion event ColormapNotify ClientMessage, PropertyNotify, SelectionClear, SelectionNotify, SelectionRequest Client communication events _________________________________________________________________ 8.2. Event Structures Each event type has a corresponding structure declared in <X11/Xlib.h>. All event structures have a member called type, which the X server sets to the event type constant name that uniquely identifies it. For example, when the X server reports a GraphicsExpose event to a client applica- tion, it sends an XGraphicsExposeEvent structure with the type member set to the constant GraphicsExpose. Each event structure also has a display member, which Xlib sets to a pointer to the display the event was read on. The X server may send events at any time in the input stream, even between the time your client application sends a request and receives a reply. Xlib stores in an event queue any events received while waiting for a reply for later use. Xlib also provides several functions that allow you to check events in the event queue, and these are dis- cussed in Section 8.6. In addition to the individual structures declared for each event type, there is also a generic XEvent structure. The XEvent structure is a union of the individual structures declared for each event type. Once you determine the event type, use the structures declared in <X11/Xlib.h> when mak- ing references to it in a client application. All events contain a ``type'' member that determines the format of the information. Depending on the type, you should access ele- ments of each event by using the XEvent union. 8.3. Event Mask Clients select event reporting of most events relative to a window. To do this, you pass an event mask to an Xlib event-handling function that takes an event_mask argument. The bits of the event mask are defined in <X11/X.h>. Each bit in the event mask maps to an event mask name. The event mask name describes the event or events you want the X server to return to a client application. When referring to a specific event mask, this manual uses the constant name defined in this file. December 18, 1987 - 228 - Most events are not reported to clients when they are gen- erated, unless the client has specifically asked for them. GraphicsExpose and NoExpose, however, are reported, by default, as a result of XCopyPlane and XCopyArea, unless the client suppresses them by setting graphics_expose in the GC to False. See Section 6.2 for further information. Selec- tionClear, SelectionRequest, SelectionNotify or ClientMes- sage cannot be masked, but they generally are only sent to clients cooperating with selections. See Section 4.4 for further information. MappingNotify is always sent to clients when the keyboard mapping is changed. The following table lists the event mask constants you can pass to the event_mask argument and the circumstances in which you would want to specify the event mask. ________________________________________________________________ Event Mask Circumstances ________________________________________________________________ NoEventMask No events wanted KeyPressMask Keyboard down events wanted KeyReleaseMask Keyboard up events wanted ButtonPressMask Pointer button down events wanted ButtonReleaseMask Pointer button up events wanted EnterWindowMask Pointer window entry events wanted LeaveWindowMask Pointer window leave events wanted PointerMotionMask Pointer motion events wanted PointerMotionHintMask Pointer motion hints wanted Button1MotionMask Pointer motion while button 1 down Button2MotionMask Pointer motion while button 2 down Button3MotionMask Pointer motion while button 3 down Button4MotionMask Pointer motion while button 4 down Button5MotionMask Pointer motion while button 5 down ButtonMotionMask Pointer motion while any button down KeymapStateMask Any keyboard state change wanted ExposureMask Any exposure wanted VisibilityChangeMask Any change in visibility wanted StructureNotifyMask Any change in window structure wanted ResizeRedirectMask Redirect resize of this window SubstructureNotifyMask Substructure notification wanted SubstructureRedirectMask Redirect substructure of window FocusChangeMask Any change in input focus wanted PropertyChangeMask Any change in property wanted ColormapChangeMask Any change in Colormap wanted OwnerGrabButtonMask Automatic grabs should activate when owner_events is True ________________________________________________________________ December 18, 1987 - 229 - 8.4. Event Processing The event types reported to a client application during event processing depend on which event masks you pass to the event_mask argument of the XSelectInput function (Section 8.5). For some event masks, there is a one-to-one correspondence between the event mask constant and the event type constant. For example, if you pass the event mask But- tonPressMask, the X server sends back only ButtonPress events. Most events contain a time member that is the time at which an event occurred. In other cases, one event mask constant can map to several event type constants. For example, if you pass the event mask SubstructureNotifyMask, the X server can send back Cir- culateNotify, ConfigureNotify, CreateNotify, DestroyNotify, GravityNotify, MapNotify, ReparentNotify, or UnmapNotify events. In another case, two event mask constants map to one event type constant. For example, if you pass the event mask PointerMotionMask or PointerMotionHintMask the X server sends back a MotionNotify event. The following table lists the event mask, its associated event type or types, and the structure name associated with the event type. Note that the letters N.A. appear in columns for which the information is not applicable. _____________________________________________________________________ Event Mask Event Type Structure _____________________________________________________________________ ButtonMotionMask MotionNotify XPointerMovedEvent Button1MotionMask Button2MotionMask Button3MotionMask Button4MotionMask Button5MotionMask ButtonPressMask ButtonPress XButtonPressedEvent ButtonReleaseMask ButtonRelease XButtonReleasedEvent ColormapChangeMask ColormapNotify XColormapEvent EnterWindowMask EnterNotify XEnterWindowEvent ExposureMask Expose XExposeEvent GraphicsExpose XGraphicsExposeEvent NoExpose XNoExposeEvent LeaveWindowMask LeaveNotify XLeaveWindowEvent FocusChangeMask FocusIn XFocusInEvent FocusOut XFocusOutEvent KeymapStateMask KeymapNotify XKeymapEvent December 18, 1987 - 230 - _____________________________________________________________________ Event Mask Event Type Structure _____________________________________________________________________ KeyPressMask KeyPress XKeyPressedEvent KeyRelease XKeyReleasedEvent OwnerGrabButtonMask N.A. N.A. PointerMotionMask MotionNotify XPointerMovedEvent PointerMotionHintMask PropertyChangeMask PropertyNotify XPropertyEvent ResizeRedirectMask ResizeRequest XResizeRequestEvent StructureNotifyMask CirculateNotify XCirculateEvent ConfigureNotify XConfigureEvent DestroyNotify XDestroyWindowEvent GravityNotify XGravityEvent MapNotify XMapEvent ReparentNotify XReparentEvent UnmapNotify XUnmapEvent SubstructureNotifyMask CirculateNotify XCirculateEvent ConfigureNotify XConfigureEvent CreateNotify XCreateWindowEvent DestroyNotify XDestroyWindowEvent GravityNotify XGravityEvent MapNotify XMapEvent ReparentNotify XReparentEvent UnmapNotify XUnmapEvent SubstructureRedirectMask CirculateRequest XCirculateRequestEvent ConfigureRequest XConfigureRequestEvent MapRequest XMapRequestEvent N.A. ClientMessage XClientMessageEvent N.A. MappingNotify XMappingEvent N.A. SelectionClear XSelectionClearEvent N.A. SelectionNotify XSelectionEvent N.A. SelectionRequest XSelectionRequestEvent VisibilityChangeMask VisibilityNotify XVisibilityEvent _____________________________________________________________________ The sections below describe the processing that occurs when you pass the different event masks to XSelectInput (Section 8.5). The sections are organized according to these process- ing categories: o Keyboard and pointer event processing December 18, 1987 - 231 - o Window crossing event processing o Input focus event processing o Key map state notification event processing o Exposure event processing o Window state notification event processing o Structure control event processing o Color map state notification event processing o Client communication event processing The processing descriptions include explanations of the structure or structures associated with the event. All the event structures contain the members type and display, which were discussed in Section 8.2. Thus, the explanations for these members are not repeated in the following sections. 8.4.1. Keyboard and Pointer Event Processing This section discusses the event processing that occurs when a pointer button is pressed and when the keyboard events KeyPress and KeyRelease and the pointer motion events But- tonPress, ButtonRelease, and MotionNotify are generated. 8.4.1.1. Pointer Button Specific Processing The following describes the event processing that occurs when a pointer button is pressed with the pointer in some window w and when no active pointer grab is in progress. The X server searches the ancestors of w from the root down, looking for a passive grab to activate. If no matching pas- sive grab on the button exists, the X server automatically starts an active grab for the client receiving the event and sets the last-pointer-grab time to the current server time. The effect is essentially equivalent to an XGrabButton with these client passed arguments: w The event window event_maskThe client's selected pointer motion events on the event window. pointer_modeGrabModeAsync. keyboard_modeGrabModeAsync. December 18, 1987 - 232 - owner_eventsTrue, if the client has selected OwnerGrabBut- tonMask on the event window; otherwise, False. confine_toNone. cursor None. The grab is automatically terminated when all buttons are released. Clients can modify the active grab by calling XUngrabPointer and XChangeActivePointerGrab. 8.4.1.2. Common Keyboard and Pointer Event Processing This section discusses the processing that occurs for the keyboard events KeyPress and KeyRelease and the pointer motion events ButtonPress, ButtonRelease, and MotionNotify. See Chapter 10 for information about the keyboard event han- dling utility functions provided in XLib. The X server can report KeyPress events to clients wanting information about when a key is pressed and KeyRelease events to clients wanting information about when a key is released. The X server generates these events whenever a key changes state, that is, whenever the key is pressed or released. Note that these events are generated for all keys, even those mapped to modifier bits. The X server reports ButtonPress events to clients wanting information about when a pointer button is pressed and ButtonRelease events to clients wanting information about when a pointer button is released. The X server generates these events whenever a pointer button changes state, that is, whenever the pointer button is pressed or released. The X server reports MotionNotify events to clients wanting information about when the pointer moves. The X server gen- erates this event whenever the pointer changes state, that is, whenever the pointer is moved and the pointer motion begins and ends in the window. The granularity of MotionNo- tify events is not guaranteed, but a client that selects this event type is guaranteed to receive at least one event when the pointer moves and then rests. To receive KeyPress, KeyRelease, ButtonPress, and Button- Release events in a client application, you pass a window ID and KeyPressMask, KeyReleaseMask, ButtonPressMask, and But- tonReleaseMask as the event_mask arguments to XSelectInput. To receive MotionNotify events in a client application, you pass a window ID and one or more of the following event masks as the event_mask argument to XSelectInput: o Button1MotionMask-Button5MotionMask December 18, 1987 - 233 - The client application receives MotionNotify events only when one or more of the specified buttons is pressed. o ButtonMotionMask The client application receives MotionNotify events only when at least one button is pressed. o PointerMotionMask The client application receives MotionNotify events independent of the state of the pointer buttons. o PointerMotionHint If PointerMotionHintMask is selected, the X server is free to send only one MotionNotify event (with the is_hint member of the XPointerMovedEvent structure set to NotifyHint) to the client for the event window, until either the key or button state changes, or the pointer leaves the event window, or the client calls the XQueryPointer or XGetMotionEvents functions. The source of the event is the smallest window containing the pointer. The window used by the X server to report these events depends on its position in the window hierarchy and whether any intervening window prohibits the generation of these events. The X server searches up the window hierarchy, starting with the source window, until it locates the first window specified by a client as having an interest in these events. If one of the intervening windows has its do_not_propagate_mask set to prohibit generation of the event type, the event of those types will be suppressed. Clients can modify the actual window used for reporting by performing active grabs, and, in the case of keyboard events, by using the focus window. See Chapter 7 for a dis- cussion of the XGrabPointer, XGrabKeyboard, and XSetInput- Focus functions. The structures associated with these events are XKeyPressedEvent, XKeyReleasedEvent, XButtonPressedEvent, XButtonReleasedEvent, and XPointerMovedEvent. The window the event is reported with respect to is called the event window. These structures have the following common members: window, root, subwindow, time, x, y, x_root, y_root, state, and same_screen. The window member is set to the window ID of the window on which the event was generated and is referred to as the event window. This is the window used by the X server to report the event, as long as the conditions discussed in the previous paragraph are met. The root member is set to the window ID of the source window's root window. The x_root December 18, 1987 - 234 - and y_root members are set to the pointer's coordinates relative to the root window's origin at the time of the event. The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be one of the constants True or False. If True, the event and root windows are on the same screen. If False, the event and root windows are not on the same screen. If the source window is an inferior of the event window, the subwindow member of the structure is set to the child of the event window that is an ancestor of or is the source member. Otherwise, the X server sets the subwindow member to the constant None. The time member is set to the time when the event was generated and is expressed in milliseconds since the server reset. If the event window is on the same screen as the root win- dow, the x and y members are set to the coordinates relative to the event window's origin. Otherwise, these members are set to zero. The state member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. For the state of the pointer buttons, the X server can set this member to the bitwise inclusive OR of one or more of the button or modifier key masks: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. Each of these structures also has a member that indicates the detail. For the XKeyPressedEvent and XKeyReleasedEvent structures, this member is called keycode. It is set to a number that represents a physical key on the keyboard. The keycode is an arbitrary representation for any key on the keyboard. See Chapter 10 for more information on the key- code. For the XButtonPressedEvent and XButtonReleasedEvent struc- tures, this member is called button. It represents the pointer buttons that changed state and can be set to the bitwise inclusive OR of one or more of these button names: Button1, Button2, Button3, Button4, Button5. For the XPoin- terMovedEvent structure, this member is called is_hint. It can be set to one of these constants: NotifyNormal or NotifyHint. 8.4.2. Window Entry/Exit Event Processing This section describes the processing that occurs for the window crossing events EnterNotify and LeaveNotify. If a pointer motion or a window hierarchy change causes the December 18, 1987 - 235 - pointer to be in a different window than before, the X server reports EnterNotify or LeaveNotify events to clients who have selected for these events. All EnterNotify and LeaveNotify events caused by a hierarchy change are gen- erated after any hierarchy event ( UnmapNotify, MapNotify, ConfigureNotify, GravityNotify, CirculateNotify) caused by that change, but the ordering of EnterNotifyand LeaveNotify events with respect to FocusOut, VisibilityNotify, and Expose events is not constrained by the X protocol. This contrasts with MotionNotify events, which are also gen- erated when the pointer moves, but the pointer motion begins and ends in a single window. An EnterNotify or LeaveNotify event may also be generated when some client application calls XChangeActivePointerGrab, XGrabKeyboard, XGrabPointer, and XUngrabPointer. To receive EnterNotify events in a client application, you must pass a window ID and EnterWindowMask as the event_mask argument to XSelectInput. Likewise, to receive LeaveNotify events, you pass the window ID and LeaveWindowMask. The members of the XEnterWindowEvent and XLeaveWindowEvent structures associated with these events are window, root, subwindow, time, x, y, x_root, y_root, mode, detail, same_screen, focus, and state. The pointer position reported in the event is always the final position, not the initial position of the pointer. The window member is set to the window ID of the window on which the EnterNotify or LeaveNotify event was generated and is referred to as the event window. This is the window used by the X server to report the event, and is relative to the root window on which the event occurred. The root member is the root window for this position and is set to the window ID of the root window on which the event occurred. In a LeaveNotify event, if a child of the event window con- tains the initial position of the pointer, the subwindow component is set to that child. Otherwise, the X server sets the subwindow member to the constant None. For an EnterNotify event, if a child of the event window contains the final pointer position, the subwindow component is set to that child. Otherwise, it is set to the constant None. The time member is set to the time when the event was gen- erated and is expressed in milliseconds. The x and y members are set to the coordinates of the pointer position in the event window. This position is always the final position of the pointer, not the initial position of the pointer. If the event window is on the same screen as the root window, x and y are the pointer coordinates relative to the event window's origin. Otherwise, x and y are set to zero. The x_root and y_root members are set to the December 18, 1987 - 236 - pointer's coordinates relative to the root window's origin at the time of the event. The same_screen member is set to indicate whether the event window is on the same screen as the root window and can be one of the constants True or False. If True, the event and root windows are on the same screen. If False, the event and root windows are not on the same screen. The focus member is set to indicate whether the event window is the focus window or an inferior of the focus window. The X server can set this member to the constants True or False. If True, the event window is the focus window or an inferior of the focus window. If False, the event window is not the focus window or an inferior of the focus window. The state member is set to indicate the state of the pointer buttons and modifier keys just prior to the event. For the state of the pointer buttons, the X server can set this member to the bitwise inclusive OR of one or more of the button or modifier key masks: Button1Mask, Button2Mask, Button3Mask, Button4Mask, Button5Mask, ShiftMask, LockMask, ControlMask, Mod1Mask, Mod2Mask, Mod3Mask, Mod4Mask, Mod5Mask. The mode member is set to indicate whether the events are normal events, pseudo-motion events when a grab activates, or pseudo-motion events when a grab deactivates. The X server can set this member to the corresponding constants NotifyNormal, NotifyGrab, or NotifyUngrab. The detail member is set to indicate the notify detail and can be one of these constants: NotifyAncestor, NotifyVir- tual, NotifyInferior, NotifyNonlinear, or NotifyNonlinear- Virtual. The following sections discuss how the X server processes normal pointer motion events and pseudo motion events. 8.4.2.1. Normal Entry/Exit Event Processing EnterNotify and LeaveNotify events are generated when the pointer moves from one window to another window. Normal events are identified by XEnterWindowEvent or XLeaveWin- dowEvent structures whose mode member is set to the constant NotifyNormal. o When the pointer moves from window A to window B, and A is an inferior of B, the X server generates: - A LeaveNotify event on window A with the detail member of the XLeaveWindowEvent structure set to the constant NotifyAncestor. December 18, 1987 - 237 - - A LeaveNotify event on each window between window A and window B exclusive, with the detail member of each XLeaveWindowEvent structure set to the constant NotifyVirtual. - An EnterNotify event on window B with the detail member of the XEnterWindowEvent structure set to the constant NotifyInferior. o When the pointer moves from window A to window B, and B is an inferior of A, the X server generates: - A LeaveNotify event on window A with the detail member of the XLeaveWindowEvent structure set to the constant NotifyInferior. - An EnterNotify event on each window between window A and window B exclusive, with the detail member of each XEnterWindowEvent structure set to the constant NotifyVirtual. - An EnterNotify event on window B with the detail member of the XEnterWindowEvent structure set to the constant NotifyAncestor. o When the pointer moves from window A to window B, and window C is their least common ancestor, the X server generates: - A LeaveNotify event on window A with the detail member of the XLeaveWindowEvent structure set to the constant NotifyNonlinear. - A LeaveNotify event on each window between window A and window C exclusive, with the detail member of each XLeaveWindowEvent structure set to the constant NotifyNonlinearVirtual. - An EnterNotify event on each window between window C and window B exclusive, with the detail member of each XEnterWindowEvent structure set to the constant NotifyNonlinearVirtual. - An EnterNotify event on window B with the detail member of the XEnterWindowEvent structure set to the constant NotifyNonlinear. o When the pointer moves from window A to window B on different screens, the X server: - Generates a LeaveNotify event on window A with the detail member of the XLeaveWindowEvent structure set to the constant NotifyNonlinear. December 18, 1987 - 238 - - If window A is not a root window, it generates a LeaveNotify event on each window above window A up to and including its root, with the detail member of each XLeaveWindowEvent structure set to the constant NotifyNonlinearVirtual. - If window B is not a root window, it generates an EnterNotify event on each window from window B's root down to but not including window B, with the detail member of each XEnterWindowEvent structure set to the constant NotifyNonlinearVirtual. - Generates an EnterNotify event on window B with the detail member of the XEnterWindowEvent struc- ture set to the constant NotifyNonlinear. - Generates an EnterNotify event on window B with the detail member of the XEnterWindowEvent struc- ture set to the constant NotifyNonlinear. 8.4.2.2. Grab and Ungrab Entry/Exit Event Processing Pseudo-motion mode EnterNotify and LeaveNotify events are generated when a pointer grab activates or deactivates. Events in which the pointer grab activates are identified by XEnterWindowEvent or XLeaveWindowEvent structures whose mode member is set to the constant NotifyGrab. Events in which the pointer grab deactivates are identified by XEnterWin- dowEvent or XLeaveWindowEvent structures whose mode member is set to the constant NotifyUngrab. See the discussion of XGrabPointer discussed in Chapter 7. o When a pointer grab activates but after any initial warp into a confine_to window, and before generating any actual ButtonPress event that activates the grab, with G the grab_window for the grab and P the window the pointer is in, the X server: - Generates EnterNotify and LeaveNotify events (see Section 8.4.2.1) with the mode members of the XEn- terWindowEvent and XLeaveWindowEvent structures set to the constant NotifyGrab. These events are generated as if the pointer were to suddenly warp from its current position in P to some position in G. However, the pointer does not warp, and the X server uses the pointer position as both the ini- tial and final positions for the events. o When a pointer grab deactivates but after generating any actual ButtonRelease event that deactivates the grab, with G the grab_window for the grab and P the window the pointer is in, the X server: December 18, 1987 - 239 - - Generates EnterNotify and LeaveNotify events (see Section 8.4.2.1) with the mode members of the XEn- terWindowEvent and XLeaveWindowEvent structures set to the constant NotifyUngrab. These events are generated as if the pointer were to suddenly warp from some position in G to its current posi- tion in P. However, the pointer does not warp, and the X server uses the current pointer position as both the initial and final positions for the events. 8.4.3. Input Focus Events This section describes the processing that occurs for the input focus events FocusIn and FocusOut. The X server can report FocusIn or FocusOut events to clients wanting infor- mation about when the input focus changes. The input focus is where the keyboard input goes. The keyboard is always attached to some window, typically, the root window or a top-level window, which is called the focus window. The focus window and the position of the pointer determines the window that receives keyboard input. Clients may need to know when the input focus changes. This is often used to control highlighting of areas of the screen. See also the focus member enter/exit events in Section 8.4.2. This can occur when a client calls XGrabKeyboard and XUngrabKeyboard. To receive FocusIn and FocusOut events in a client applica- tion, you pass a window ID and FocusChangeMask as the event_mask argument to XSelectInput. The members of the XFocusInEvent and XFocusOutEvent struc- tures associated with these events are window, mode, and detail. The window member is set to the window ID of the window on which the FocusIn or FocusOut event was generated. This is the window used by the X server to report the event. The mode member is set to indicate whether the focus events are normal focus events, while grabbed focus events, focus events when a grab activates, or focus events when a grab deactivates. The X server can set the mode member to the corresponding constants NotifyNormal, NotifyWhileGrabbed, NotifyGrab, or NotifyUngrab. The following sections discuss how the X server processes normal focus events, while grabbed focus events, and grab activate/deactivate focus events. All FocusOut events caused by a window unmap are generated after any UnmapNotify event, but the ordering of FocusOut events with respect to generated EnterNotify, LeaveNotify, VisibilityNotify, and Expose events is not constrained by the X protocol. Depending on the event mode, the detail member is set to indicate the notify detail and can be one of these December 18, 1987 - 240 - constants: NotifyAncestor, NotifyVirtual, NotifyInferior, NotifyNonlinear, NotifyNonlinearVirtual, NotifyPointer, NotifyPointerRoot, or NotifyDetailNone, 8.4.3.1. Normal and While Grabbed Focus Event Processing Normal focus events are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to the constant NotifyNormal. While grabbed focus events are iden- tified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to the constant NotifyWhileGrabbed. The X server processes normal focus and while grabbed focus events according to the following focus scenarios: o When the focus moves from window A to window B, and A is an inferior of B with the pointer in window P, the X server: - Generates a FocusOut event on window A with the detail member of the XFocusOutEvent structure set to the constant NotifyAncestor. - Generates a FocusOut event on each window between window A and window B exclusive, with the detail member of each XFocusOutEvent structure set to the constant NotifyVirtual. - Generates a FocusIn event on window B with the detail member of the XFocusOutEvent structure set to the constant NotifyInferior. - If window P is an inferior of window B, but window P is not window A or an inferior of window A, it generates a FocusIn event on each window below window B down to and including window P, with the detail member of each XFocusInEvent structure set to the constant NotifyInferior. o When the focus moves from window A to window B, and B is an inferior of A with the pointer in window P, the X server: - If window P is an inferior of window A, but P is not A, or an inferior of window B, or an ancestor of B, it generates a FocusOut event on each window from window P up to but not including window A (in that order), with the detail member of each XFocu- sOutEvent structure set to the constant NotifyPointer. - Generates a FocusOut event on window A with the detail member of the XFocusOutEvent structure set to the constant NotifyInferior. December 18, 1987 - 241 - - Generates a FocusIn event on each window between window A and window B exclusive, with the detail member of each XFocusInEvent structure set to the constant NotifyVirtual. - Generates a FocusIn event on window B with the detail member of the XFocusInEvent structure set to the constant NotifyAncestor o When the pointer moves from window A to window B, and window C is their least common ancestor, and with the pointer in window P, the X server: - If window P is an inferior of window A, it gen- erates a FocusOut event on each window from window P up to but not including window A, with the detail member of the XFocusOutEvent structure set to the constant NotifyPointer. - Generates a FocusOut event on window A with the detail member of the XFocusOutEvent structure set to the constant NotifyNonlinear. - Generates a FocusOut event on each window between window A and window C exclusive, with the detail member of each XFocusOutEvent structure set to the constant NotifyNonlinearVirtual. - Generates a FocusIn event on each window between C and B exclusive, with the detail member of each XFocusInEvent structure set to the constant NotifyNonlinearVirtual. - Generates a FocusIn event on window B with the detail member of the XFocusInEvent structure set to the constant NotifyNonlinear. - If window P is an inferior of window B, it gen- erates a FocusIn event on each window below window B down to and including window P, with the detail member of the XFocusInEvent structure set to the constant NotifyPointer. o When the focus moves from window A to window B on dif- ferent screens with the pointer in window P, the X server: - If window P is an inferior of window A, it gen- erates a FocusOut event on each window from window P up to but not including window A, with the detail member of each XFocusOutEvent structure set to the constant NotifyPointer. December 18, 1987 - 242 - - Generates a FocusOut event on window A with the detail member of the XFocusOutEvent structure set to the constant NotifyNonlinear. - If window A is not a root window, it generates a FocusOut event on each window above window A up to and including its root, with the detail member of each XFocusOutEvent structure set to the constant NotifyNonlinearVirtual. - If window B is not a root window, it generates a FocusIn event on each window from window B's root down to but not including window B, with the detail member of each XFocusInEvent structure set to the constant NotifyNonlinearVirtual. - Generates a FocusIn event on window B with the detail member of each XFocusInEvent structure set to the constant NotifyNonlinear. - If window P is an inferior of window B, it gen- erates a FocusIn event on each window below window B down to and including window P, with the detail member of each XFocusInEvent structure set to the constant NotifyPointer. o You may have specified the focus window by passing the constant PointerRoot (or None), when you called the function XSetInputFocus. (See Chapter 7.) When the focus moves from window A to PointerRoot (events sent to the window under the pointer) or None (discard), with the pointer in window P, the X server: - If window P is an inferior of window A, it gen- erates a FocusOut event on each window from window P up to but not including window A, with the detail member of each XFocusOutEvent structure set to the constant NotifyPointer. - Generates a FocusOut event on window A with the detail member of the XFocusOutEvent structure set to NotifyNonlinear. - If window A is not a root window, it generates a FocusOut event on each window above window A up to and including its root, with the detail member of each XFocusOutEvent structure set to NotifyNon- linearVirtual. - Generates a FocusIn event on the root window of all screens with the detail member of each XFocu- sInEvent structure set to NotifyPointerRoot (or NotifyDetailNone). December 18, 1987 - 243 - - If the new focus is PointerRoot, it generates a FocusIn event on each window from window P's root down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointerRoot. o When the focus moves from PointerRoot (events sent to the window under the pointer) or None to window A, with the pointer in window P, the X server: - If the old focus is PointerRoot, it generates a FocusOut event on each window from window P up to and including window P's root, with the detail member of each XFocusOutEvent structure set to NotifyPointerRoot (in order). - Generates a FocusOut event on all root windows with the detail member of each XFocusOutEvent structure set to NotifyPointerRoot (or NotifyDe- tailNone). - If window A is not a root window, it generates a FocusIn event on each window from window A's root down to but not including window A, with the detail member of each XFocusInEvent structure set to NotifyNonlinearVirtual. - Generates a FocusIn event on window A with the detail member of the XFocusInEvent structure set to the constant NotifyNonlinear. - If window P is an inferior of window A, it gen- erates a FocusIn event on each window below window A down to and including window P, with the detail member of each XFocusInEvent structure set to the constant NotifyPointer. o When the focus moves from PointerRoot (events sent to the window under the pointer) to None (or vice versa), with the pointer in window P, the X server: - If the old focus is PointerRoot, it generates a FocusOut event on each window from window P up to and including window P's root, with the detail member of each XFocusOutEvent structure set to NotifyPointerRoot. - Generates a FocusOut event on all root windows with the detail member of each XFocusOutEvent structure set to the constant NotifyPointerRoot or NotifyDetailNone. December 18, 1987 - 244 - - Generates a FocusIn event on all root windows with the detail member of each XFocusInEvent structure set to NotifyDetailNone or NotifyPointerRoot. - If the new focus is PointerRoot, it generates a FocusIn event on each window from window P's root down to and including window P, with the detail member of each XFocusInEvent structure set to NotifyPointerRoot. 8.4.3.2. Focus Events Generated by Grabs Focus events in which the keyboard grab activates are iden- tified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to the constant NotifyGrab. Focus events in which the keyboard grab deactivates are identified by XFocusInEvent or XFocusOutEvent structures whose mode member is set to the constant NotifyUngrab. See the discussion of XGrabKeyboard in Chapter 7. o When a keyboard grab activates but before generating any actual KeyPress event that activates the grab with G the grab_window and F the current focus, the X server: - Generates FocusIn and FocusOut events (as dis- cussed in the previous section), with the mode members of the XFocusInEvent and XFocusOutEvent structures set to the constant NotifyGrab. These events are generated as if the focus were to change from F to G. o When a keyboard grab deactivates but after generating any actual KeyRelease event that deactivates the grab with G the grab_window and F the current focus, the X server: - Generates FocusIn and FocusOut events (as dis- cussed in the previous section), with the mode members of the XFocusInEvent and XFocusOutEvent structures set to the constant NotifyUngrab. These events are generated as if the focus were to change from G to F. 8.4.4. Key Map State Notification Event Processing This section discusses the processing that occurs for the key map state notification event KeymapNotify. The X server reports KeymapNotify events to clients wanting information about changes in the keyboard state. To receive KeymapNo- tify events in a client application, you pass a window ID and KeymapStateMask as the event_mask argument to XSelectIn- put. The X server generates this event immediately after every EnterNotify and FocusIn event. December 18, 1987 - 245 - The members of the XKeymapEvent structure associated with this event are window and key_vector. The window member is not used but is present to aid some toolkits. The key_vector member is set to the bit vector of the keyboard. Each one bit indicates that the corresponding key is currently pressed. The vector is represented as 32 bytes. Byte N (from 0) contains the bits for keys 8N to 8N+7 with the least significant bit in the byte representing key 8N. 8.4.5. Exposure Event Processing The X protocol does not guarantee to preserve the contents of window regions when the windows are obscured or reconfig- ured. Some implementations may preserve the contents of windows. Many other implementations will feel free to des- troy the contents of windows when exposed. X expects client applications to assume the responsibility for restoring the contents of an exposed window region. (An exposed window region describes a formerly obscured window whose region or piece of a region becomes visible). Therefore, the X server sends exposure events describing the window and the region of the window that has been exposed. A trivial client application usually redraws the entire window. A more sophisticated client application redraws only the exposed region. The following sections discuss the processing that occurs for the Expose, GraphicsExpose, and NoExpose exposure events. 8.4.5.1. Expose Event Processing The X server can report Expose events to clients wanting information about when the contents of window regions have been lost. The circumstances in which the X server gen- erates Expose events are not as definite as those for other events. However, the X server never generates Expose events on windows whose class you specified as InputOnly. The X server can possibly generate Expose events when a window region becomes viewable, but it might only generate this event when a region becomes visible. The X server guaran- tees to report contiguously all of the regions exposed by some action, such as raising a window. To receive Expose events in a client application, you pass a window ID and ExposureMask as the event_mask argument to XSelectInput. The members of the XExposeEvent structure associated with this event are window, x, y, width, height, and count. The window member is set to the window ID of the exposed (dam- aged) window. The x and y members are set to the coordi- nates relative to the drawable's origin and indicate the upper left corner of the rectangle. The width and height members are set to the size (extent) of the rectangle. The count member is set to the number of Expose events that are December 18, 1987 - 246 - to follow. If count is set to 0 (zero), no more Expose events follow for this window. However, if count is set to nonzero, at least count Expose events and possibly more fol- low for this window. Simple applications that do not want to optimize redisplay by distinguishing between subareas of its window can just ignore all Expose events with nonzero counts and perform full redisplays on events with zero counts. 8.4.5.2. GraphicsExpose and NoExpose Event Processing The X server can report GraphicsExpose events to clients wanting information about when a destination region could not be computed during a graphics request. Clients initiate a graphics request by calling XCopyArea or XCopyPlane. The X server generates this event whenever a destination region could not be computed due to an obscured or out-of-bounds source region. In addition, the X server guarantees to report contiguously all of the regions exposed by some graphics request (for example, copying an area of a drawable to a destination drawable). The X server generates NoExpose events whenever a graphics request that might produce a GraphicsExpose event does not produce any. In other words, the client is really asking for a GraphicsExpose event but instead receives a NoExpose event. To receive GraphicsExpose or NoExpose events in a client application, you must first set the graphics_exposures member of the XGCValues structure for the associated graph- ics context to the constant True. You did this when you created the graphics context by calling XCreateGC. Or, you may have set the graphics_exposures member after creating the graphics context by calling XSetGraphicsExposures. See Chapter 5 for more information on these functions. The structures associated with these event types are XGra- phicsExposeEvent and XNoExposeEvent, and they have these common members: drawable, major_code, and minor_code. The drawable member is set to the drawable ID of the destination region on which the copy request was to be performed. The major_code member is set to the graphics request initiated by the client, and can be one of the constants X_CopyArea or X_CopyPlane. If X_CopyArea, a call to XCopyArea initiated the request. If X_CopyPlane, a call to XCopyPlane initiated the request. These constants are defined in <X11/Xproto.h>. The minor_code member, like the major_code member, indicates which graphics request was initiated by the client. However, the minor_code member is not defined by the core X protocol and will be zero in these cases, but may be used by an extension. The XGraphicsExposeEvent structure has these additional December 18, 1987 - 247 - members: x, y, width, height, and count. The x and y members are set to the coordinates relative to the drawable's origin and indicate the upper left corner of the rectangle. The width and height members are set to the size (extent) of the rectangle. The count member is set to the number of Gra- phicsExpose events to follow. If count is set to 0 (zero), no more GraphicsExpose events follow for this window. How- ever, if count is set to nonzero, at least that many more, and possibly more, GraphicsExpose events are to follow for this window. 8.4.6. Window State Notification Event Processing The following sections discuss the processing that occurs for these window state notification events: CirculateNo- tify, ConfigureNotify, CreateNotify, DestroyNotify, Gravi- tyNotify, MapNotify, MappingNotify, ReparentNotify, UnmapNo- tify, and VisibilityNotify. 8.4.6.1. CirculateNotify Event Processing The X server can report CirculateNotify events to clients wanting information about when a window changes its position in the stack. The X server generates this event type when- ever a window is actually restacked as a result of a client application calling XCirculateSubwindows, XCirculateSubwin- dowsUp, or XCirculateSubwindowsDown. To receive this event type in a client application, you pass the window ID and StructureNotifyMask as the event_mask argument to XSelectInput. You can also receive this event type by passing the parent window ID and SubstructureNo- tifyMask. The members of the XCirculateEvent structure associated with this event are event, window, and place. The event member is set to the window ID of the window on which the Circula- teNotify event was generated. This is the window used by the X server to report the event. The window member is set to the window ID of the window that was restacked. The place member is set to the window's position after the res- tack occurs, and is one of the constants PlaceOnTop or Pla- ceOnBottom. If PlaceOnTop, the window is now on top of all siblings. If PlaceOnBottom, the window is now below all siblings. 8.4.6.2. ConfigureNotify Event Processing The X server can report ConfigureNotify events to clients wanting information about actual changes to a window's state, that is, size, position, border, stacking order. The X server generates this event type whenever one of the fol- lowing configure window requests made by a client applica- tion actually completes: December 18, 1987 - 248 - o A window's size, position, border, and stacking order is reconfigured as a result of calling XConfigureWin- dow. o The window's position in the stacking order is changed as a result of calling XLowerWindow, XRaiseWindow, or XRestackWindows. o A window is moved as a result of calling XMoveWindow. o A window's size is changed as a result of calling XResizeWindow. o A window's size and location is changed as a result of calling XMoveResizeWindow. o A window is mapped and its position in the stacking order is changed as a result of calling XMapRaised. o A window's border width is changed as a result of cal- ling XSetWindowBorderWidth. To receive this event type in a client application, you pass the window ID and StructureNotifyMask as the event_mask argument to XSelectInput. You can also receive this event type by passing the parent window ID and SubstructureNo- tifyMask. The members of the XConfigureEvent structure associated with this event are event, window, x, y, width, height, border_width, above, and override_redirect. The event member is set to the window ID of the window on which the ConfigureNotify event was generated. This is the window used by the X server to report the event. The window member is set to the window ID of the window whose size, position, border, and/or stacking order was changed. The x and y members are set to the coordinates relative to the new parent window's origin and indicate the position of the upper left outside corner of the window. The width and height members are set to the inside size of the window, not including the border. The border_width member is set to the width of the window's border, in pixels. The above member is set to the window ID of the sibling win- dow and is used for stacking operations. If the X server sets this member to the constant None, the window whose state was changed is on the bottom of the stack with respect to sibling windows. However, if this member is set to the ID of a sibling window, the X server places the window whose state was changed on top of this sibling window. The override_redirect member is set to the constant you specified for the override_redirect member of the December 18, 1987 - 249 - XSetWindowAttributes structure when you created the window or changed its attributes. This constant is either True or False. Window manager clients normally should ignore this event if the override_redirect member is True. 8.4.6.3. CreateNotify Event Processing The X server can report CreateNotify events to clients want- ing information about creation of windows. The X server generates this event whenever a client application creates a window by calling XCreateWindow or XCreateSimpleWindow. To receive this event type in a client application, you pass the window ID of the parent window and SubstructureNo- tifyMask as the event_mask argument to XSelectInput. The members of the XCreateWindowEvent structure associated with this event are parent, window, x, y, width, height, border_width, and override_redirect. The parent member is set to the window ID of the created window's parent. The window member specifies the window ID of the created window. The x and y members are set to the created window's coordi- nates relative to the inside of the parent window's borders and indicate the position of the upper left outside corner of the created window. The width and height members are set to the inside size of the created window not including the border, and are always a nonzero value. The border_width member is set to the width of the created window's border, in pixels. The override_redirect member is set to the con- stant you specified for the override_redirect member of the XSetWindowAttributes structure when you created the window or changed its attributes. This constant is either True or False. Window manager clients normally should ignore this event if the override_redirect member is True. 8.4.6.4. DestroyNotify Event Processing The X server can report DestroyNotify events to clients wanting information about which windows are destroyed. The X server generates this event whenever a client application destroys a window by calling XDestroyWindow or XDestroy- Subwindows. The ordering of the DestroyNotify events is such that for any given window, DestroyNotify is generated on all inferi- ors of the window before being generated on the window itself. The ordering among siblings and across subhierar- chies is not otherwise constrained by the X protocol. To receive this event type in a client application, you pass the window ID of the parent window and SubstructureNo- tifyMask as the event_mask argument to XSelectInput. You can also receive this event type by passing the window ID of the window and SubstructureNotifyMask. December 18, 1987 - 250 - The members of the XDestroyWindowEvent structure associated with this event are event and window. The event member is set to the window ID of the window on which the DestroyNo- tify event was generated. This is the window used by the X server to report the event. The window member is set to the window ID of the window that is destroyed. 8.4.6.5. GravityNotify Event Processing The X server can report GravityNotify events to clients wanting information about when a window is moved because of a change in the size of its parent. The X server generates this event whenever a client application actually moves a child window as a result of resizing its parent by calling XConfigureWindow, XMoveResizeWindow, and XResizeWindow. To receive this event type in a client application, you pass the window ID of the window and StructureNotifyMask as the event_mask argument to XSelectInput. You can also receive this event type by passing the window ID of the parent win- dow and SubstructureNotifyMask. The members of the XGravityEvent structure associated with this event are event, window, x, and y. The event member is set to the window ID of the window on which the GravityNo- tify event was generated. This is the window used by the X server to report the event. The window member is set to the window ID of the child window that was moved. The x and y members are set to the coordinates relative to the new parent window's origin and indicate the position of the upper left outside corner of the window. 8.4.6.6. MapNotify Event Processing The X server can report MapNotify events to clients wanting information about which windows are mapped. The X server generates this event type whenever a client application changes the window's state from unmapped to mapped by cal- ling XMapWindow, XMapRaised, or XMapSubwindows. To receive this event type, you pass the window ID of the window and StructureNotifyMask as the event_mask argument to XSelectInput. You can also receive this event type by pass- ing the window ID of a parent window and SubstructureNo- tifyMask. The members of the XMapEvent structure associated with this event are event, window, and override_redirect. The event member is set to the window ID of the window on which the MapNotify event was generated. This is the window used by the X server to report the event. The window member is set to the window ID of the window that was mapped. The override_redirect member is set to the constant you speci- fied for the override_redirect member of the December 18, 1987 - 251 - XSetWindowAttributes structure, when you created the window or changed its attributes. This constant is either True or False. Window manager clients normally should ignore this event if the override_redirect member is True. 8.4.6.7. MappingNotify Event Processing The X server reports MappingNotify events to all clients. There is no mechanism to express disinterest in this event. The X server generates this event type whenever a client application calls: o XSetModifierMapping to indicate which keycodes are to be used as modifiers. The status reply must be Mapping- Success. o XChangeKeyboardMapping to change the keyboard mapping. o XSetPointerMapping to set the pointer mapping. The status reply must be MappingSuccess. See Chapter 7 for a discussion of these functions. The members of the XMappingEvent structure associated with this event are window (not used and only present to aid cer- tain toolkits), request, first_keycode, and count. The request member is set to indicate the kind of mapping change that occurred, and can be one of the constants MappingModif- ier, MappingKeyboard, MappingPointer. If MappingModifier, the specified keycodes are used as modifiers. If Mapping- Keyboard, the keyboard mapping is changed. If Mapping- Pointer, the pointer button mapping is set. The first_keycode and count members are set only if the request member was set to MappingKeyboard. If this is the case, these members are set to numbers that indicate the range of altered keyboards. Thus, the number in first_keycode represents the first number in the range, and the number in count represents the last number in the range. To update the client application's knowledge of the key- board, you should call XRefreshKeyboardMapping. See Chapter 10 for a discussion of this function. 8.4.6.8. ReparentNotify Event Processing The X server can report ReparentNotify events to clients wanting information about changing a window's parent. The X server generates this event whenever a client application calls XReparentWindow and the window is actually reparented. To receive this event type in a client application, you pass the window ID of the old or the new parent window and Sub- StructureNotifyMask as the event_mask argument to XSelectIn- put. You can also receive this event type by passing the December 18, 1987 - 252 - window ID and StructureNotifyMask. The members of the XReparentEvent structure associated with this event are event, window, parent, x, y, and override_redirect. The event member is set to the window ID of the window on which the ReparentNotify event was gen- erated and on which you requested notification by using XSelectInput. This is the window used by the X server to report the event. The window member is set to the window ID of the window that was reparented. The parent member is set to the window ID of the new parent window. The x and y members are set to the reparented window's coordinates rela- tive to the new parent window's origin and define the upper left outer corner of the reparented window. The override_redirect member is set to the constant you speci- fied for the override_redirect member of the XSetWindowAt- tributes structure when you created the window or changed its attributes. This constant is either True or False. Window manager clients normally should ignore this event if the override_redirect member is True. 8.4.6.9. UnmapNotify Event Processing The X server can report UnmapNotify events to clients want- ing information about which windows are unmapped. The X server generates this event type whenever a client applica- tion changes the window's state from mapped to unmapped by calling XUnmapWindow or XUnmapSubwindows. To receive this event type, you pass the window ID and StructureNotifyMask as the event_mask argument to XSelectIn- put. You can also receive this event type by passing the window ID of the parent window and SubstructureNotifyMask. The members of the XUnmapEvent structure associated with this event are event, window, and from_configure. The event member is set to the window ID of the window on which the UnmapNotify event was generated and on which you requested notification by using XSelectInput. This is the window used by the X server to report the event. The window member is set to the window ID of the window that was unmapped. The from_configure member is set to the constant True if the event was generated as a result of a resizing of the window's parent when the window itself had a win_gravity of UnmapGravity. 8.4.6.10. VisibilityNotify Event Processing The X server can report VisibilityNotify events to clients wanting any change in the visibility of the specified win- dow. A region of a window is visible if someone looking at the screen can actually see it. The X server generates this event whenever the visibility changes state. However, this event is never generated for windows whose class is December 18, 1987 - 253 - InputOnly. X ignores any subwindows in this computation. All VisibilityNotify events caused by a hierarchy change are generated after any hierarchy event ( UnmapNotify, MapNo- tify, ConfigureNotify, GravityNotify, CirculateNotify) caused by that change. Any VisibilityNotify event on a given window is generated before any Expose events on that window, but it is not required that all VisibilityNotify events on all windows be generated before all Expose events on all windows. The ordering of VisibilityNotify events with respect to FocusOut, EnterNotify, and LeaveNotify events is not constrained by the X protocol. To receive this event type in a client application, you pass the window ID of the window and VisibilityChangeMask as the event_mask argument to XSelectInput. The members of the XVisibilityEvent structure associated with this event are window and state. The window member is set to the window whose visibility state changes. The state member is set to the state of the window's visibility, and can be one of the constants VisibilityUnobscured, Visibili- tyPartiallyObscured, or VisibilityFullyObscured. The X server ignores all of a window's subwindows when determining the visibility state of the window and processes Visibili- tyNotify events according to the following: o When the window changes state from partially or fully obscured or not viewable to viewable and completely unobscured, the X server generates the event with the state member of the XVisibilityEvent structure set to the constant VisibilityUnobscured. o When the window changes state from viewable and com- pletely unobscured or from not viewable to viewable and partially obscured, the X server generates the event with the state member of the XVisibilityEvent structure set to the constant VisibilityPartiallyObscured. o When the window changes state from viewable and com- pletely unobscured or viewable and partially obscured or from not viewable to viewable and fully obscured, the X server generates the event with the state member of the XVisibilityEvent structure set to the constant VisibilityFullyObscured. 8.4.7. Structure Control Event Processing The following sections discuss the processing that occurs for these structure control events: CirculateRequest, Con- figureRequest, MapRequest, and ResizeRequest. These are only generated when clients have structure control enabled and are generally only of interest to window managers. December 18, 1987 - 254 - 8.4.7.1. CirculateRequest Event The X server can report CirculateRequest events to clients wanting information about when another client initiates a circulate window request on a specified parent window. The X server generates this event type whenever a client initiates a circulate window request on a parent window, and a window actually needs to be restacked. The client initiates a cir- culate window request on the parent window by calling XCir- culateSubwindows, XCirculateSubwindowsUp, or XCircula- teSubwindowsDown. To receive this event type in a client application, you pass the window ID of the parent window and Substruc- tureRedirectMask as the event_mask argument to XSelectInput. In the future, the circulate window request for the speci- fied window will not be not executed, and, thus, the window's position in the stack is not changed. For example, suppose a client application calls XCirculateSubwindowsUp to raise a specified window to the top of the stack. If you had selected SubstructureRedirectMask on the parent window, the X server reports to you a CirculateRequest event and does not raise the specified window to the top of the stack. The members of the XCirculateRequestEvent structure associ- ated with this event are parent, window, and place. The parent member is set to the window ID of the parent window. The window member is set to the window ID of the window to be restacked. The place member is set to what the new posi- tion in the stacking order should be, and is one of the con- stants PlaceOnTop or PlaceOnBottom. If PlaceOnTop, the win- dow should be on top of all siblings. If PlaceOnBottom, the window should be below all siblings. 8.4.7.2. ConfigureRequest Event The X server can report ConfigureRequest events to clients wanting information about when another client initiates a configure window request on a specified window. The config- ure window request attempts to reconfigure a window's size, position, border, and stacking order. The X server gen- erates this event whenever a client initiates a configure window request on a window by calling XConfigureWindow, XLowerWindow, XRaiseWindow, XMapRaised, XMoveResizeWindow, XMoveWindow, XResizeWindow, XRestackWindows, or XSetWin- dowBorderWidth. To receive this event type in a client application, you pass the window ID of the parent window and Substruc- tureRedirectMask as the event_mask argument to XSelectInput. It is generated when a ConfigureWindow request is issued on the window by another client. For example, suppose a client application calls XLowerWindow to lower a window. If you had selected SubstructureRedirectMask on the parent window, December 18, 1987 - 255 - and if the override_redirect member of the XSetWindowAttri- butes structure associated with the specified window is set to False, the X server reports a ConfigureRequest event to you and does not lower the specified window. The members of the XConfigureRequestEvent structure associ- ated with this event are parent, window, x, y, width, height, border_width, above, detail, and value_mask. The parent member is set to the window ID of the parent window. The window member is set to the window ID whose size, posi- tion, border width, and/or stacking order is to be reconfig- ured. The x and y members are set to the coordinates rela- tive to the parent window's origin and indicate the desired position of the upper left outside corner of the reconfig- ured window. The width and height members are set to the desired inside size of the reconfigured window (not includ- ing the border) and are always a nonzero value. The border_width member is set to the desired width of the reconfigured window's border, in pixels. The above member is set to the window ID of the sibling window and is used for stacking operations. If the X server sets this member to the constant None, then the reconfigured window should be placed on the bottom of the stack with respect to sibling windows. However, if this member is set to the ID of a sibling window, the reconfigured window wants to be placed on top of this sibling window. If not given in the request, the detail member is set to the constant Above. This member could also be set to the con- stants Below, TopIf, BottomIf, or Opposite. The value_mask member is set to indicate which components were specified in the request. The value_mask and the corresponding values are reported as given in the request. 8.4.7.3. MapRequest Event The X server can report MapRequest events to clients wanting information about another client's desire to map (place) windows. A window is considered mapped when a map window request completes. The X server generates this event when- ever a client initiates a map window request on an unmapped window whose override_redirect member is set to False. Clients initiate map window requests by calling XMapWindow, XMapRaised, or XMapSubwindows. To receive this event type in a client application, you pass the window ID of the parent window and Substruc- tureRedirectMask as the event_mask argument to XSelectInput. This means another client's attempts to map the window by calling one of the map window request functions will fail, and you will be sent a MapRequest instead. For example, suppose a client application calls XMapWindow to map a win- dow. If you (usually your window manager) had selected Sub- structureRedirectMask on the parent window, and if the December 18, 1987 - 256 - override_redirect member of the XSetWindowAttributes struc- ture associated with the specified window is set to False, the X server reports to you a MapRequest event and does not map the specified window. Thus, this event gives your win- dow manager client the ability to control the placement of subwindows. The members of the XMapRequestEvent structure associated with this event are parent and window. The parent member is set to the window ID of the parent window. The window member is set to the window ID of the window to be mapped. 8.4.7.4. ResizeRequest Event Processing The X server can report ResizeRequest events to clients wanting information about another client's attempts to change the size of a window. The X server generates this event whenever some other client attempts to change the size of the specified window by calling XConfigureWindow, XResizeWindow, or XMoveResizeWindow. To receive this event type in a client application, you pass a window ID and ResizeRedirect as the event_mask argument to XSelectInput. You will be sent the ResizeRedirect event, and any attempts to change the size by other clients will fail. The members of the XResizeRequestEvent structure associated with this event are window, width, and height. The window member is set to the window ID of the window whose size another client attempted to change. The width and height members are set to the inside size of the window, not including the border. 8.4.8. Color Map State Notification Event Processing This section discusses the processing that occurs for the color map notification event ColormapNotify. The X server can report ColormapNotify events to clients wanting informa- tion about when the color map changes and when a color map is installed or uninstalled. The X server generates this event type whenever a client application: o Changes the colormap member of the XSetWindowAttributes structure by calling XChangeWindowAttributes or XFreeColormap. o Installs or uninstalls the color map by calling XIn- stallColormap or XUninstallColormap. To receive this event type in a client application, you pass the window ID of the window and ColormapChangeMask to the event_mask argument of XSelectInput. December 18, 1987 - 257 - The members of the XColormapEvent structure associated with this event are window, colormap, new, and state. The window member is set to the window ID of the window whose associ- ated color map is changed, installed, or uninstalled. For a color map that is changed by a call to XChangeWindowAttri- butes, installed, or uninstalled, the colormap member is set to the colormap resource ID of the color map associated with the window. For a color map that is changed by a call to XFreeColormap, the colormap member is set to the constant None. The new member is set to indicate whether the color map for the specified window was changed or installed or uninstalled, and it can be one of the constants True or False. If True, the color map was changed. If False, the color map was installed or uninstalled. The state member is always set to indicate whether the color map is installed or uninstalled, and it can be one of the corresponding con- stants ColormapInstalled or ColormapUninstalled. 8.4.9. Client Communication Event Processing The following sections discuss the processing that occurs for these client communication events: ClientMessage, Pro- pertyNotify, SelectionClear, SelectionNotify, and Selection- Request. 8.4.9.1. ClientMessage Event Processing The X server generates ClientMessage events only when a client calls the function XSendEvent. See Section 8.8 in this chapter for information on how to send an event. The members of the XClientMessageEvent structure associated with this event are window, message_type, format, and data. The window member is set to the window ID of the window to which the event was sent. The message_type member is set to an atom that indicates how the data is to be interpreted by the receiving client. The format member is set to 8, 16, or 32 and specifies whether the data should be viewed as a list of bytes, shorts, or longs. The data member is a union that contains the members b, s, and l. The b, s, and l members represent data of twenty 8-bit values, ten 16-bit values, and five 32-bit values. Particular message types might not make use of all these values. The X server places no interpretation on the values in the message_type or data members. 8.4.9.2. PropertyNotify Event Processing The X server can report PropertyNotify events to clients wanting information about property changes for a specified window. A property consists of an atom name, an atom type, a data format, and some property data. The X server gen- erates this event whenever a client application calls XChangeProperty, XDeleteProperty, XRotateWindowProperties, December 18, 1987 - 258 - XGetProperty. See Chapter 4 for more information on these functions and the property concept. To receive this event type, you pass the window ID and Pro- pertyChangeMask as the event_mask argument to XSelectInput. The members of the XPropertyEvent structure associated with this event are window, atom, time, and state. The window member is set to the window ID of the window whose associ- ated property was changed. The atom member is set to the property's atom and indicates which property was changed or desired. The time member is set to the server time when the property was changed. The state member is set to indicate whether the property was changed to a new value or deleted, and it can be one of the corresponding constants Proper- tyNewValue or PropertyDelete. 8.4.9.3. SelectionClear Event Processing The X server reports SelectionClear events to the current owner of a selection. The X server generates this event type on the window losing ownership of the selection to a new owner. This sequence of events could occur whenever a client calls XSetSelectionOwner. See Section 4.4 for infor- mation on this function and on selections. The members of the XSelectionClearEvent structure associated with this event are window, selection, and time. The window member is set to the ID of the window losing ownership of the selection. The selection member is set to the selection atom. The time member is set to the last change time recorded for the selection. The owner member is the window that was specified by the current owner in its XSetSelec- tionOwner call. 8.4.9.4. SelectionRequest Event Processing The X server reports SelectionRequest events to the owner of a selection. The X server generates this event whenever a client requests a selection conversion by calling XConvert- Selection, and the specified selection is owned by a window. The members of the XSelectionRequestEvent structure associ- ated with this event are owner, requestor, selection, tar- get, property, and time. The owner member is set to the window ID of the window owning the selection. The owner member is the window that was specified by the current owner in its XSetSelectionOwner call. The requestor member is set to the window ID of the window requesting the selection. The selection member is set to the atom that indicates which selection. For example, PRIMARY is used to indicate the primary selection. The target member is set to the atom December 18, 1987 - 259 - that indicates the type the selection is desired in. The property member can be the atom or the property or None. The time member is set to the time and is a timestamp, expressed in milliseconds, or the constant CurrentTime from the ConvertSelection request. The client whose window owns the selection should do the following: o Convert the selection based on the atom contained in the target member. o If a property was specified (that is, the property member is set), the client should store the result as that property on the requestor window and then send a SelectionNotify event to the requestor by calling XSen- dEvent with an empty event-mask, that is the event should be sent to the creator of the requestor window. o If the selection cannot be converted as requested, the client should send a SelectionNotify event with the property set to the constant None. 8.4.9.5. SelectionNotify Event Processing This event is generated by the X server in response to a XConvertSelectionrequest When there is an owner, it should be generated by the owner of the selection by using XSen- dEvent. The owner of a selection should send this event to a requestor when a selection has been converted and stored as a property. or when a selection conversion could not be performed (indicated with the property member set to None). The members of the XSelectionEvent structure associated with this event are requestor, selection, target, property, and time. The requestor member is set to the window ID of the window associated with the requestor of the selection. The selection member is set to the atom that indicates the kind of selection. For example, PRIMARY is used for the primary selection. The target member is set to the atom that indi- cates the desired type. For example, PIXMAP is used for a pixmap. The property member is set to the atom that indi- cates which property the result was stored on. If none were possible, then the property member will be set to None. The time member is set to the time in which the conversion took place and can be a timestamp, expressed in milliseconds, or the constant CurrentTime. 8.5. Selecting Events There are two ways to select the events you want reported to your client application. One way is to set the event_mask member of the XSetWindowAttributes structure when you call XCreateWindow and XChangeWindowAttributes. See Chapter 3 December 18, 1987 - 260 - for a discussion of these functions. Another way is to use XSelectInput. Section 8.4 discussed the processing that occurs for each event type associated with the event mask you pass to XSelectInput. Event Handling The definition for XSelectInput is: XSelectInput(display, w, event_mask) Display *display; Window w; unsigned long event_mask; display Specifies the connection to the X server. w Specifies the window ID. Client applications interested in an event for a particular window pass that window's ID. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. The XSelectInput function requests that the X server report the events associated with the event masks that you pass to the event_mask argument. Initially, X will not report any of these events. See Section 8.3 for a discussion of these event masks. Events are reported relative to a window. If a window is not interested in an event, it usually propagates to the closest ancestor that is interested, unless the do_not_propagate mask prohibits it. A call to XSelectInput overrides any previous call to XSelectInput for the same window from the same client but not for other clients. Two different clients can select events on the same window with the following restrictions: o Multiple clients can select events on the same window because their event masks are disjoint. After the X server generates an event, it reports it to all interested clients. o Only one client at a time can select CirculateRequest, ConfigureRequest, or MapRequest events, which are asso- ciated with the event mask SubstructureRedirectMask. o Only one client at a time can select a ResizeRequest event, which is associated with the event mask Resiz- eRedirectMask. December 18, 1987 - 261 - o Only one client at a time can select a ButtonPress event, which is associated with the event mask But- tonPressMask. If a client passes both ButtonPressMask and Button- ReleaseMask for a specified window, a ButtonPress event in that window will automatically grab the mouse until all but- tons are released and ButtonRelease events are sent to win- dows as described for XGrabPointer. This ensures that a window will see the ButtonRelease event corresponding to the ButtonPress event, even though the mouse may have exited the window in the meantime. If a client passes PointerMotionMask, the X server sends MotionNotify events independent of the state of the pointer buttons. If, instead, the client passes one or more of Button1MotionMask, Button2MotionMask, Button3MotionMask, Button4MotionMask, Button5MotionMask, the X server generates MotionNotify events only when one or more of the specified buttons is depressed. These are used to request MotionNo- tify events only when particular buttons are held down. The errors that can be generated by XSelectInput are BadWin- dow and BadValue. 8.6. Handling the Output Buffer and the Event Queue Xlib provides functions with which you can flush the output buffer. In addition to flushing the output buffer, some of these functions also perform additional tasks, such as checking the event queue. The following sections discuss how to: o Flush the output buffer o Flush the output buffer and check the event queue o Put an event back on the queue 8.6.1. Flushing the Output Buffer The output buffer is an area used by the Xlib library to store requests. The functions described in this section are similar in that they flush the output buffer. That is, all requests residing in the output buffer that have not yet been sent are transmitted to the X server. Conversely, these functions differ in the additional tasks they might perform. For example, XSync not only flushes the output buffer, but it can also discard all events on the event queue. The following paragraphs describe the functions XFlush, XSync, and XPending. Use XFlush to flush the output buffer. The definition for December 18, 1987 - 262 - this function is: XFlush(display) Display *display; display Specifies the connection to the X server. The XFlush function flushes the output buffer. Most client applications need not use this function because the output buffer is automatically flushed the next time an event or reply is read from the output buffer by a call to XPending, XNextEvent, or XWindowEvent. Use XSync to flush the output buffer and then wait until all requests have been processed. The definition for this func- tion is: XSync(display, discard) Display *display; int discard; display Specifies the connection to the X server. discard Specifies whether XSync discards all events on the event queue. You can pass the value 0 or 1. The XSync function flushes the output buffer. It then waits until all events (including error events) have been received and processed by the X server. In addition, this function places the events recently processed by the X server on the event queue. For each error event received and processed by the X server, XSync calls the client application's XError routine. Finally, if you passed the value 0 to the discard argument, XSync does not discard the events on the queue. If you passed the value 1, this function discards all events on the queue, including those events that were on the queue before XSync was called. Client applications use XSync less often than they would use XFlush. Use XPending to flush the output buffer and return the number of events pending. The definition for this function is: int XPending(display) Display *display; December 18, 1987 - 263 - display Specifies the connection to the X server. The XPending function flushes the output buffer. It then returns the number of events received from the X server but not yet removed from the event queue. (You remove events from the queue by calling XNextEvent or XWindowEvent.) You should call XPending before blocking or waiting for new events (for example, calling the select system call on a UNIX-based system). The events you are waiting for may have already arrived and be sitting in Xlib's queue. 8.6.2. Flushing the Output Buffer and Checking the Event Queue As discussed in the previous section, the output buffer is an area used by the X server to store requests. The func- tions described in this section are similar in that they all flush the output buffer and then check the event queue to see if the next event on the queue is the one wanted by the client. Conversely, these functions differ in what they do with the event after checking it on the event queue. These functions also differ in whether they pass a predicate pro- cedure. The functions XNextEvent and XPeekEvent do not take a predicate procedure and are discussed first. Subsequent paragraphs describe the predicate procedure and the func- tions that pass it: XIfEvent, XCheckIfEvent, and XPeekI- fEvent. Use XNextEvent to flush the output buffer, copy the next event, and then remove it from the event queue. The defini- tion for this function is: XNextEvent(display, event_return) Display *display; XEvent *event_return; display Specifies the connection to the X server. event_returnThe XNextEvent function copies the event's asso- ciated structure into this client-supplied struc- ture. The XNextEvent function flushes the output buffer. If the event queue is empty, XNextEvent blocks until an event is received. It then removes an event from the head of the queue and copies its associated structure into a client- supplied XEvent structure. For example, if a CreateNotify event is at the head of the queue, this function removes it and then copies the structure XCreateWindowEvent into XEvent. December 18, 1987 - 264 - Use XPeekEvent to flush the output buffer and peek at the event queue. The definition for this function is: XPeekEvent(display, event_return) Display *display; XEvent *event_return; display Specifies the connection to the X server. event_returnThe XPeekEvent function copies the event's asso- ciated structure into this client-supplied struc- ture. The XPeekEvent function flushes the output buffer. If the queue is empty, XPeekEvent blocks until an event is received. It then peeks at an event from the head of the queue and copies its associated structure into the client- supplied XEvent structure without removing it from the event queue. For example, if a CreateNotify event is at the head of the queue, this function peeks at it but does not remove it and then copies the structure XCreateWindowEvent into XEvent. You can use the QLength macro to determine if there are any events to peek at. Each of the functions discussed in the following paragraphs requires you to pass a predicate procedure that determines if the event matches the one specified in the corresponding function. The predicate procedure and its associated argu- ments are: Bool (*predicate)(display, event, args) Display *display; XEvent *event; char *args; display Specifies the connection to the X server. event Specifies a pointer to the structure XEvent. This structure is a union of the individual structures declared for each event type. args Specifies the arguments passed in from the XIfEvent, XCheckIfEvent, or XPeekIfEvent function. The predicate procedure is called once for each event in the queue until it finds a match between the event in the queue and the event specified by the corresponding function. After finding a match, the predicate procedure must return True or False if it did not find a match. December 18, 1987 - 265 - Use XIfEvent to flush the output buffer, check the event queue for the specified event, and, if the events match, remove the event from the queue. The definition for this function is: XIfEvent(display, event_return, predicate, arg) Display *display; XEvent *event_return; Bool (*predicate)(); char *arg; display Specifies the connection to the X server. event_returnThe XIfEvent function copies the matched event's associated structure into this client-supplied structure. predicate Specifies the procedure that is to be called to determine if the next event in the queue matches the one specified by the event argument. arg Specifies the user-supplied argument that will be passed to the predicate procedure. The XIfEvent function flushes the output buffer. It com- pletes only when the specified predicate procedure returns a nonzero (true) for an event, which indicates an event on the queue matches the specified event. This predicate procedure is also called each time an event is added to the queue. XIfEvent removes the event from the queue and, when it returns, copies the structure into the client-supplied XEvent structure. Use XCheckIfEvent to flush the output buffer and check the event queue for the specified event without blocking. The definition for this function is: Bool XCheckIfEvent(display, event_return, predicate, arg) Display *display; XEvent *event_return; Bool (*predicate)(); char *arg; display Specifies the connection to the X server. event_returnThe XCheckIfEvent function copies the matched event's associated structure into this client- supplied structure. December 18, 1987 - 266 - predicate Specifies the procedure that is to be called to determine if the next event in the queue matches the one specified by the event argument. arg Specifies the user-supplied argument that will be passed to the predicate procedure. The XCheckIfEvent function flushes the output buffer. It completes only when the specified predicate procedure returns True for the next event in the queue that matches the specified event. If the predicate procedure finds a match, XCheckIfEvent copies the matched event into the client-supplied XEvent structure and returns True (This event is removed from the queue.) If the predicate pro- cedure finds no match, XCheckIfEvent returns False. All earlier events stored in the queue are not discarded. Use XPeekIfEvent to flush the output buffer, check the event queue for the specified event, but not remove the event from the queue. The definition for this function is: XPeekIfEvent(display, event_return, predicate, arg) Display *display; XEvent *event_return; Bool (*predicate)(); char *arg; display Specifies the connection to the X server. event_returnThe XPeekIfEvent function copies the matched event's associated structure into this client- supplied structure. predicate Specifies the procedure that is to be called to determine if the next event in the queue matches the one specified by the event argument. arg Specifies the user-supplied argument that will be passed to the predicate procedure. The XPeekIfEvent function flushes the output buffer. It returns only when the specified predicate procedure returns a nonzero (true) for the next event in the queue that matches the specified event. This predicate procedure is called each time an event is added to the queue. After the predicate procedure finds a match, XPeekIfEvent copies the matched event into the client-supplied XEvent structure without removing the event from the queue. December 18, 1987 - 267 - 8.6.3. Putting an Event Back onto the Queue Use XPutBackEvent to push an event back to the top of the event queue. The definition for this function is: XPutBackEvent(display, event) Display *display; XEvent *event; display Specifies the connection to the X server. event Specifies a pointer to the XEvent structure. This structure is a union of the individual structures declared for each event type. The XPutBackEvent function pushes an event back onto the head of the current display's event queue. This can be use- ful if you have read an event and then decide that you would rather deal with it later. There is no limit to how many times in succession you can call XPutBackEvent. 8.7. Selecting Events from the Event Queue The functions described in this section are similar in that they all flush the output buffer. That is, all requests residing in the output buffer that have not yet been sent are transmitted to the client application. These functions also allow you to select event types. By allowing you to select event types, you can process events out of order. Conversely, these functions differ in the way they process these events. Yet, several require you to pass an event mask. See Section 8.3. for a discussion of the valid event mask names. Use XWindowEvent to remove the next matched event for the specified window. The definition for this function is: XWindowEvent(display, w, event_mask, event_return) Display *display; Window w; long event_mask; XEvent *event_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose next matched event you want to remove. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. December 18, 1987 - 268 - event_returnThe XWindowEvent function copies the matched event's associated structure into this client- supplied structure. The XWindowEvent function flushes the output buffer. It then searches the event queue for the events associated with the specified window. XWindowEvent removes the next event in the queue that matches both the window and the event mask that you passed. It then copies the event's associated structure into the client-supplied XEvent structure. All earlier events stored in the queue are not discarded. If the event you requested is not in the queue, XWindowEvent blocks until one is received. Use XCheckWindowEvent to remove the next event that matches both the passed window and the passed mask. This function is very similar to XWindowEvent, except it does not block, and it returns a zero (0) or one (1) value. The definition for this function is: Bool XCheckWindowEvent(display, w, event_mask, event_return) Display *display; Window w; int event_mask; XEvent *event_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose next matched event you want to remove. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. event_returnThe XCheckWindowEvent function copies the matched event's associated structure into this client-supplied structure. The XCheckWindowEvent function flushes the output buffer. It then searches the event queue for the events associated with the specified window. XCheckWindowEvent removes the next event in the queue that matches both the window and the event mask that you passed. It then copies the event's associated structure into the client-supplied XEvent struc- ture and returns True. All earlier events stored in the queue are not discarded. If the event you requested is not in the queue, XCheckWindowEvent immediately returns False. Use XMaskEvent to remove the next event in the queue that matches the passed mask. The definition for this function December 18, 1987 - 269 - is: XMaskEvent(display, event_mask, event_return) Display *display; unsigned long event_mask; XEvent *event_return; display Specifies the connection to the X server. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. event_returnThe XMaskEvent function copies the matched event's associated structure into this client- supplied structure. The XMaskEvent function flushes the output buffer. It then searches the event queue for the events associated with the specified mask. XMaskEvent removes the next event in the queue that matches the event mask that you passed. It then copies the event's associated structure into the client- supplied XEvent structure. All earlier events stored in the queue are not discarded. If the event you requested is not in the queue, XMaskEvent blocks until one is received. Use XCheckMaskEvent to remove the next event that matches the passed mask. This function is exactly the same as XMaskEvent except that it does not block and it returns a 0 or 1 value. The definition for this function is: Bool XCheckMaskEvent(display, event_mask, event_return) Display *display; unsigned long event_mask; XEvent *event_return; display Specifies the connection to the X server. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. event_returnThe XCheckMaskEvent function copies the matched event's associated structure into this client- supplied structure. The XCheckMaskEvent function flushes the output buffer. It then searches the event queue for the events associated with the specified mask. XCheckMaskEvent removes the next event in the queue that matches the event mask that you passed. It then copies the event's associated structure into the December 18, 1987 - 270 - client-supplied XEvent structure and returns True. All ear- lier events stored in the queue are not discarded. If the event you requested is not in the queue, XCheckMaskEvent immediately returns False. Use XCheckTypedEvent to return the next event in the queue that matches an event type. The definition for this func- tion is: int XCheckTypedEvent(display, event_type, event_return) Display *display; int event_type; XEvent *event_return; display Specifies the connection to the X server. event_typeSpecifies the event type to be compared. event_returnThe XCheckTypedEvent function copies the matched event's associated structure into this client- supplied structure. The XCheckTypedEvent function flushes the output buffer, searches the event queue for the specified event type, and, if there is a match, returns its associated event structure to the specified XEvent structure. Note that events earlier in the queue are not discarded. In addition, XCheck- TypedEvent returns True if the event is found and False if the event is not found. Use XCheckTypedWindowEvent to return the next matched event in the queue for the specified window. The definition for this function is: int XCheckTypedWindowEvent(display, w, event_type, event_return) Display *display; Window w; int event_type; XEvent *event_return; display Specifies the connection to the X server. w Specifies the window ID. event_typeSpecifies the event type to be compared. December 18, 1987 - 271 - event_returnThe XCheckTypedWindowEvent function copies the matched event's associated structure into this client-supplied structure. The XCheckTypedWindowEvent function flushes the output buffer and searches the event queue for the events associ- ated with the specified window. XCheckTypedWindowEvent returns the next event that matches the window and the specified event type to the specified XEvent structure. Note that events earlier in the queue are not discarded. In addition, XCheckTypedWindowEvent returns True if the event is found and False if the event is not found. 8.8. Sending and Getting Events This section discusses how to send events and how to obtain motion events. Use XSendEvent to send an event to a speci- fied window. This function is often used in selection pro- cessing. For example, the owner of a selection should use XSendEvent to send a SelectionNotify event to a requestor when a selection has been converted and stored as a pro- perty. The definition for this function is: XSendEvent(display, w, propagate, event_mask, event_send) Display *display; Window w; Bool propagate; unsigned long event_mask; XEvent *event_send; display Specifies the connection to the X server. w Specifies the window ID. This is the window interested in the event, and is referred to as the destination window. You can pass the window ID or the constants PointerWindow or InputFocus. propagate Specifies a boolean value that is either the con- stant True or False. event_maskSpecifies the event mask. This mask is the bit- wise inclusive OR of one or more of the valid event mask bits. event_sendSpecifies a pointer to the event that is to be sent. The XSendEvent function identifies the destination window, determines which clients should receive the specified events, and ignores any active grabs. This function requires you to pass an event mask. See Section 8.3 for a discussion of the valid event mask names. This function uses the w argument to identify the destination window as December 18, 1987 - 272 - follows: o If you pass PointerWindow to w, the destination window is the window that contains the pointer. o If you pass InputFocus to w, and if the focus window contains the pointer, the destination window is the window that contains the pointer. If the focus window does not contain the pointer, the destination window is the focus window. To determine which clients should receive the specified events, XSendEvent uses the propagate argument as follows: o If propagate is False, the event is sent to every client selecting on destination any of the event types in the event_mask argument. o If propagate is True, and no clients have selected on destination any of the event types in event-mask, the destination is replaced with the closest ancestor of destination for which some client has selected a type in event-mask and for which no intervening window has that type in its do_not_propagate_mask. If no such win- dow exists or if the window is an ancestor of the focus window and InputFocus was originally specified as the destination, the event is not sent to any clients. Otherwise, the event is reported to every client selecting on the final destination any of the types specified in event_mask. The events in the XEvent structure must be one of the core events or one of the events defined by a loaded extension, so that the X server can correctly byte swap the contents as necessary. The contents of the event are otherwise unaltered and unchecked by the X server except to force on the most significant bit of the event code. Many X server implementations will maintain a more precise history of mouse motion between event notification. The mouse position at each mouse hardware interrupt may be stored into a buffer for later retrieval. This is called the motion history buffer. For example, a few applications, best exemplified by paint programs, want to have a precise history of where the mouse traveled. However, this is highly excessive for most applications. The errors that can be generated by XSendEvent are BadWindow and BadValue. 8.9. Getting Pointer Motion Events Use XGetMotionEvents to return motion events for a specified December 18, 1987 - 273 - window and the number of these events in the motion history buffer. The definition for this function is: XTimeCoord *XGetMotionEvents(display, w, start, stop, nevents_return) Display *display; Window w; Time start, stop; int *nevents_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose associated pointer motion events you want to retrieve. start stop Specify the time interval in which the events are returned from the motion history buffer. You can pass a time stamp, expressed in milliseconds, or the constant CurrentTime. If the stop time is in the future, it is equivalent to specifying CurrentTime. nevents_returnReturns the number of events from the motion history buffer. The XGetMotionEvents function returns all events in the motion history buffer that fall between the specified start and stop times inclusive and that have coordinates that lie within (including borders) the specified window at its present placement. If the start time is later than the stop time or if the start time is in the future, no events are returned. The return type for this function is a structure defined as follows: typedef struct { Time time; unsigned short x, y; } XTimeCoord; The time member is set to the time, in milliseconds. The x and y members are set to the coordinates of the pointer and are reported relative to the origin of the specified window. You should use XFree to free the data returned from this call. (See Section 2.4 for further information.) The error that can be generated by XGetMotionEvents is BadWindow. December 18, 1987 - 274 - 8.10. Handling Error Events Xlib provides functions with which you can: o Enable or disable synchronization o Use the default error handlers The following sections discuss the functions associated with these tasks. Error Handling 8.10.1. Enabling or Disabling Synchronization When debugging X applications, it can be very convenient to require the library to behave synchronously, so that errors are reported at the time they occur. The routine below allows you to disable or enable synchronous behavior. Note that graphics may occur dramatically slower when enabled (30 or more times slower). On UNIX-based systems, there is also a global variable _Xdebug that if set to nonzero before starting a program under a debugger will force synchronous library behavior. Use XSynchronize to enable or disable synchronization. The definition for this function is: int (*XSynchronize(display, onoff))() Display *display; int onoff; display Specifies the connection to the X server. onoff Specifies whether to enable or disable synchroni- zation. Possible values you can pass are 0 (dis- able synchronization) or nonzero (enable synchron- ization). The XSynchronize function returns the previous after func- tion. If onoff is nonzero, XSynchronize turns on synchro- nous behavior. A value of zero (0) resets the state to off (disable synchronous behavior). After completing their work, all Xlib functions that gen- erate protocol requests call what is known as a previous after function. XSetAfterFunction sets which function is to be called. The definition for this function is: int (*XSetAfterFunction(display, proc))() Display *display; int (*proc)(); December 18, 1987 - 275 - display Specifies the connection to the X server. proc Specifies the function to be called after an Xlib function that generates a protocol request com- pletes its work. The specified proc will be called with only a display pointer. 8.10.2. Using the Default Error Handlers There are two default error handlers in the library, one to handle typically fatal conditions (for example, the connec- tion to a display server dying due to a machine crash), and one to handle error events from the X server. These error handlers can be changed to user-supplied routines if you prefer your own error handling and can be changed as often as you like. If either of these routines are passed a NULL pointer, it will reinvoke the default handler. The default action of the supplied routine is to print an explanatory message and exit. This section discusses: XSetEr- rorHandler, XGetErrorText, XGetErrorDatabaseText, XDisplay- Name, and XSetIOErrorHandler. Use XSetErrorHandler to handle error events. The definition for this function is: XSetErrorHandler(handler) int (*handler)(Display *, XErrorEvent *) handler Specifies the program's supplied error handler. The program's supplied error hander will be called by Xlib whenever an XError event is received. This is not assumed to be a fatal condition. It is acceptable for this procedure to return. However, the error handler should not perform any operations (directly or indirectly) on the display. The fields of the XErrorEvent structure passed to XError should be interpreted as follows: typedef struct { int type Display *display; /* Display the event was read from */ int serial; /* serial number of failed request */ char error_code; /* error code of failed request */ char request_code; /* Major op-code of failed request */ char minor_code; /* Minor op-code of failed request */ XID resourceid; /* resource id */ } XErrorEvent; The serial member is the number of requests starting from December 18, 1987 - 276 - one sent over the network connection since it was opened. It is the number that was the value of the request sequence number immediately after the failing call was made. The request_code member is a protocol representation of the name of the procedure that failed and are defined in <X11/X.h>. The following error codes can be returned by the functions described in this chapter: ____________________________________________________________ Error Code Description ____________________________________________________________ BadAccess A client attempted to grab a key/button combination already grabbed by another client. A client attempted to free a color map entry that it did not already allocate. A client attempted to store into a read-only color map entry. A client attempted to modify the access control list from other than the local (or otherwise authorized) host. A client attempted to select an event type that another client has already selected, and, that at most, one client can select at a time. BadAlloc The server failed to allocate the requested resource or server memory. BadAtom A value for an Atom argument does not name a defined Atom. BadColor A value for a Colormap argument does not name a defined Colormap. BadCursor A value for a Cursor argument does not name a defined Cursor. BadDrawable A value for a Drawable argument does not name a defined Window or Pixmap. BadFont A value for a Font or GContext argument does not name a defined Font. BadGC A value for a GContext argument does not name a defined GContext. BadIDChoice The value chosen for a resource identif- ier is either not included in the range assigned to the client or is already in use. Under normal circumstances this cannot occur and should be considered a server or X Library error. BadImplementation December 18, 1987 - 277 - ____________________________________________________________ Error Code Description ____________________________________________________________ The server does not implement some December 18, 1987 - 278 - ____________________________________________________________ Error Code Description ____________________________________________________________ aspect of the request. A server that generates this error for a core request is deficient. As such, this error is not listed for any of the requests. However, clients should be prepared to receive such errors and either handle or discard them. December 18, 1987 - 279 - ____________________________________________________________ Error Code Description ____________________________________________________________ December 18, 1987 - 280 - ____________________________________________________________ Error Code Description ____________________________________________________________ BadLength The length of a request is shorter or longer than that minimally required to contain the arguments. This usually means an internal Xlib error. BadMatch In a graphics request, the root and depth of the GC does not match that of the drawable. An InputOnly window is used as a Draw- able. Some argument or pair of arguments has the correct type and range but fails to match in some other way required by the request. An InputOnly window locks this attri- bute. The values do not exist for an InputOnly window. BadName A font or color of the specified name does not exist. BadPixmap A value for a Pixmap argument does not name a defined Pixmap. BadRequest The major or minor opcode does not specify a valid request. BadValue Some numeric value falls outside the range of values accepted by the request. Unless a specific range is specified for an argument, the full range defined by the argument's type is accepted. Any argument defined as a set of alterna- tives can generate this error. BadWindow A value for a Window argument does not name a defined Window. ____________________________________________________________ Note The BadAtom, BadColor, BadCursor, BadDrawable, BadFont, BadGC, BadPixmap, and BadWindow errors are also used when the argument type is extended by union with a set of fixed alternatives, for example, <Window or PointerRoot or None. December 18, 1987 - 281 - It is recommended that XError use XGetErrorText for obtain- ing textual descriptions of the specified error code. The definition for this function is: XGetErrorText(display, code, buffer_return, length) Display *display; int code; char *buffer_return; int length; display Specifies the connection to the X server. code Specifies the error code for which you want to obtain a description. buffer_returnReturns the error description. length Specifies the size of the buffer. The XGetErrorText function copies a null-terminated string describing the specified error code into the specified buffer. It is recommended that you use this routine to obtain an error description because extensions to the Xlib library may define their own error codes and error strings. Use XGetErrorDatabaseText to obtain error messages from the error data base. The definition for this function is: XGetErrorDatabaseText(display, name, message, default_string, buffer_return, length) Display display; char *name, *message; char *default_string; char *buffer_return; int length; display Specifies the connection to the X server. name Specifies the name of the application. message Specifies the type of the error message. default_stringSpecifies the default error message. buffer_returnReturns the error description. length Specifies the size of the buffer. The XGetErrorDatabaseText function returns a message (or the default masssage) from the error message database. Given a pair of strings as keys, XGetErrorDatabaseText uses the resource manager to look up a string and returns in the December 18, 1987 - 282 - buffer argument. Xlib uses this function internally to look up its error messages. On a UNIX-based system, the error message database is /usr/lib/XerrorDB. The name argument should generally be the name of your application. The message argument should indicate which type of error message you want. Three predefined sets of names are used by Xlib to report errors: o XProtoError The protocol error number is used as a string for the message argument. o XlibMessage These are the message strings that are used internally by the library. o XRequestMajor The major request protocol number is used for the mes- sage argument. If no string is found in the error data base, the default_string is returned to the buffer argument. Use XDisplayName to report an error to the user when the requested display does not exist. The definition for this function is: char *XDisplayName(string) char *string; string Specifies the character string. The XDisplayName function returns the name of the display that you are currently using. If a NULL string is speci- fied, XDisplayName looks in the environment for the display and returns the display name that the user was requesting. This makes it easier to report to the user precisely which display the program attempted to open when the initial con- nection attempt failed. Use XSetIOErrorHandler to handle fatal I/O errors. The definition for this function is: XSetIOErrorHandler(handler) int (*handler)(Display *); December 18, 1987 - 283 - handler Specifies the program's supplied error handler. The XSetIOErrorHandler sets the fatal IO error handler. The program's supplied error handler will be called by Xlib if any sort of system call error occurs. For example, the con- nection to the server was lost. This is assumed to be a fatal condition. That is, the called routine should not return. If the IO error handler does return, the client process will exit. December 18, 1987 - 284 - Chapter 9 Predefined Property Functions Chapter 9 - Predefined Property Functions There are a number of predefined properties for common information usually associated with windows. The atoms for these predefined properties can be found in <X11/Xatom.h>. Xlib provides functions with which you can perform prede- fined property operations. This chapter discusses how to: o Communicate with window managers o Manipulate standard colormaps 9.1. Communicating with Window Managers This section discusses a set of properties and functions that are necessary for clients to communicate effectively with window managers. Some of these properties have complex structures. Because all the data in a single property on the server has to be of the same format (8, 16, or 32 bit), and because the C structures representing property types cannot be guaranteed to be uniform in the same way, Set and Get functions are provided for properties with complex structures to format. These functions define but do not enforce minimal policy among window managers. Writers of window managers are urged to use the information in these properties rather than invent their own properties and types. A window manager writer, however, can define additional properties beyond this proposed least common denominator. In addition to Set and Get functions for individual proper- ties, Xlib includes one function, XSetStandardProperties, that sets all or portions of several properties. The pur- pose of XSetStandardProperties is to provide a simple inter- face for the programmer who wants to code an application in an afternoon. Applications which need to communicate to the window manager more information than is possible with XSetStandardProperties should not use this interface. Instead, they should call the Set functions for the addi- tional or specific properties that they need. In order to work well with most window managers, every application should specify the following information: December 18, 1987 - 285 - o Name of the application o Name string for the icon o Command used to invoke the application o Size and window manager hints as defined below Xlib does not set defaults for the properties described in this section. Thus, the default behavior is determined by the window manager and may be based on the presence or absence of certain properties. All the properties are con- sidered to be hints to a window manager. When implementing window management policy, a window manager determines what to do with this information and is allowed to ignore it. The supplied properties are: __________________________________________________________________ Name Type Format Description __________________________________________________________________ WM_NAME STRING 8 Name of the applica- tion WM_ICON_NAME STRING 8 Name to be used in icon WM_NORMAL_HINTS WM_SIZE_HINTS 32 Size hints for a win- dow in its normal state. The C type of this property is XSizeHints (see below). WM_ZOOM_HINTS WM_SIZE_HINTS 32 Size hints for a zoomed window. The C type of this property is XSizeHints (see below). WM_HINTS WM_HINTS 32 Additional hints set by client for use by the window manager. The C type of this property is XWMHints (see below). WM_COMMAND STRING 8 The command and argu- ments, separated by ASCII 0s, used to invoke the applica- tion. WM_ICON_SIZE WM_ICON_SIZE 32 The window manager may set this property on the root window to specify the icon sizes December 18, 1987 - 286 - __________________________________________________________________ Name Type Format Description __________________________________________________________________ it supports. The C type of this property is XIconSize (see below). December 18, 1987 - 287 - __________________________________________________________________ Name Type Format Description __________________________________________________________________ December 18, 1987 - 288 - __________________________________________________________________ Name Type Format Description __________________________________________________________________ WM_CLASS STRING 32 Set by application programs to allow win- dow and session managers to obtain the application's resources from the resource database. WM_TRANSIENT_FOR WINDOW 32 Set by application programs to indicate to the window manager that a transient top- level window, such as a dialog box, is not really a full-fledged window. __________________________________________________________________ The atom names stored in <X11/Xatom.h> are named ``XA_PROPERTY_NAME''. Xlib provides functions with which you can set and get predefined properties. Note that calling the Set function for a property with complex structure redefines all fields in that property, even though only some of those fields may have a specified new value. Simple properties for which Xlib does not provide a Set or Get function may be set using XChangeProperty and their values may be retrieved using XGetWindowProperty. The remainder of this section discusses how to: o Set standard properties o Set and get the name of a window o Set and get the icon name of a window o Set the command atom o Set and get window manager hints o Set and get window sizing hints o Set and get icon size hints o Set and get the class of a window December 18, 1987 - 289 - o Set and get the transient property for a window 9.1.1. Setting Standard Properties Use XSetStandardProperties to specify a minimum set of pro- perties describing the ``quickie'' application. This func- tion sets all or portions of the WM_NAME, WM_ICON_NAME, WM_HINTS, WM_COMMAND, WM_NORMAL_HINTS properties. The definition for this function is: XSetStandardProperties(display, w, window_name, icon_name, icon_pixmap, argv, argc, hints) Display *display; Window w; char *window_name; char *icon_name; Pixmap icon_pixmap; char **argv; int argc; XSizeHints *hints; display Specifies the connection to the X server. w Specifies the window ID. window_nameSpecifies the name of the window. icon_name Specifies the name to be displayed in the window's icon. icon_pixmapSpecifies the pixmap that is to be used for the icon or None. argv Specifies a pointer to the command and arguments used to start the application. argc Specifies the number of arguments. hints Specifies a pointer to the sizing hints for the window in its normal state. The XSetStandardProperties function provides a means by which, with a single call, simple applications set the most essential properties. XSetStandardProperties should be used to give a window manager some information about your program's preferences. It should not be used by applications which need to communicate more information than is possible with XSetStandardProperties. See Section 9.1.6 for a dis- cussion of the XSizeHints structure. The errors that can be generated by XSetStandardProperties are BadWindow and BadAlloc. December 18, 1987 - 290 - 9.1.2. Setting and Getting Window Names Xlib provides functions to set and read the name of a win- dow. These functions set and read the WM_NAME property. Use XStoreName to assign a name to a window. The definition for this function is: XStoreName(display, w, window_name) Display *display; Window w; char *window_name; display Specifies the connection to the X server. w Specifies the window ID. This is the window to which you want to assign a name. window_nameSpecifies the name of the window. The name should be a null-terminated string. This name will be returned by any subsequent call to XFetch- Name. The XStoreName function assigns the name passed to window_name to the specified window. A window manager may display the window name in some prominent place, such as the title bar, to allow users to identify windows easily. Some window managers may display a window's name in the window's icon, although they are encouraged to use the window's icon name, if one is provided by the application. The errors that can be generated by XStoreName are BadWindow and BadAlloc. Use XFetchName to get the name of a window. The definition for this function is: int XFetchName(display, w, window_name_return) Display *display; Window w; char **window_name_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose name you want a pointer set to. window_name_returnReturns a pointer to the window name, which will be a null-terminated string. December 18, 1987 - 291 - The XFetchName function obtains a window name and returns either a nonzero if it succeeds or zero (0) if it fails (for example, if no name has been set for the argument window). If the WM_NAME property has not been set for this window, XFetchName sets this argument to NULL. When finished with it, a client must free the name string using the free library subroutine. The error that can be generated by XFetchName is BadWindow. 9.1.3. Setting and Getting Icon Names Xlib provides functions to set and read the name to be displayed in a window's icon. These functions set and read the WM_ICON_NAME property. Use XSetIconName to set the name to be displayed in a window's icon. The definition for this function is: XSetIconName(display, w, icon_name) Display *display; Window w; char *icon_name; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose icon name is being set. icon_name Specifies the name to be displayed in the window's icon. The name should be a null-terminated string. This name is returned by any subsequent call to XGetIconName. The errors that can be generated by XSetIconName are BadWin- dow and BadAlloc. Use XGetIconName to get the name a window wants displayed in its icon. The definition for this function is: int XGetIconName(display, w, icon_name_return) Display *display; Window w; char **icon_name_return; display Specifies the connection to the X server. w Specifies the window ID. This is the window whose icon name you want a pointer set to. December 18, 1987 - 292 - icon_name_returnReturns a pointer to the name to be displayed in the window's icon. The name will be a null-terminated string. The XGetIconName function obtains the window name to be displayed in its icon and either returns a nonzero if it succeeds or zero (0) if it fails (for example, if no icon name has been set for the argument window). If you never assigned a name to the window, XGetIconName sets this argu- ment to NULL. When finished with it, a client must free the icon name string using the free library subroutine. The error that can be generated by XGetIconName is BadWin- dow. 9.1.4. Setting the Command Atom Use XSetCommand to set the value of the command atom. This function sets the WM_COMMAND property. The definition for this function is: XSetCommand(display, w, argv, argc) Display *display; Window w; char **argv; int argc; display Specifies the connection to the X server. w Specifies the window ID. argv Specifies a pointer to the command and arguments used to start the application. argc Specifies the number of arguments. The XSetCommand function records the command and arguments used to invoke the application. The errors that can be generated by XSetCommand are BadWin- dow and BadAlloc. 9.1.5. Setting and Getting Window Manager Hints The functions discussed in this section set and read the WM_HINTS property and use the XWMHints structure: December 18, 1987 - 293 - typedef struct { long flags; /* marks which fields in this structure are defined */ Bool input; /* does this application rely on the window manager to get keyboard input? */ int initial_state; /* see below */ Pixmap icon_pixmap; /* pixmap to be used as icon */ Window icon_window; /* window to be used as icon */ int icon_x, icon_y; /* initial position of icon */ Pixmap icon_mask; /* pixmap to be used as mask for icon_pixmap */ XID window_group; /* id of related window group */ /* this structure may be extended in the future */ } XWMHints; The definitions for the flags field are: #define InputHint (1L << 0) #define StateHint (1L << 1) #define IconPixmapHint (1L << 2) #define IconWindowHint (1L << 3) #define IconPositionHint (1L << 4) #define IconMaskHint (1L << 5) #define WindowGroupHint (1L << 6) #define AllHints (InputHint|StateHint|IconPixmapHint|IconWindowHint| \ IconPositionHint|IconMaskHint|WindowGroupHint) The input field is used to communicate to the window manager the input focus model used by the application. Applications which expect input but never explicitly set focus to any of their subwindows (use the push model of focus management), such as X10-style applications that use real-estate driven focus, should set this field to True. Similarly, applica- tions that set input focus to their subwindows only when it is given to their top-level window by a window manager should also set this field to True. Applications which manage their own input focus by explicitly setting focus to one of their subwindows whenever they want keyboard input (that is, use the pull model of focus management) should set this field to False. Applications which never expect any keyboard input should also set this field to False. Pull model window managers should make it possible for push model applications to get input by setting input focus to the top level windows of applications whose input field is True. Push model window managers should make sure that pull model applications do not break them, by resetting input focus to PointerRoot when appropriate (for example, whenever an application whose input field is False sets input focus to one of its subwindows). The definitions for the initial_state flag are: December 18, 1987 - 294 - #define DontCareState 0 /* don't know or care */ #define NormalState 1 /* most applications want to start this way */ #define ZoomState 2 /* application wants to start zoomed */ #define IconicState 3 /* application wants to start as an icon */ #define InactiveState 4 /* application believes it is seldom used; some wm's may put it on inactive menu */ The icon_mask specifies which pixels of the icon_pixmap should be used as the icon. This allows for nonrectangular pixmaps. The window_group lets you specify that this window belongs to a group of other windows. For example, if a sin- gle application manipulates multiple children of the root window, this allows you to provide enough information that a window manager can iconify all of the windows, rather than just the one window. Use XSetWMHints to set the value of the window manager hints atom. The definition for this function is: XSetWMHints(display, w, wmhints) Display *display; Window w; XWMHints *wmhints; display Specifies the connection to the X server. w Specifies the window ID. wmhints Specifies a pointer to the window manager hints. The XSetWMHints function sets the window manager hints that include icon information and location, the initial state of the window, and whether the application relies on the window manager to get keyboard input. The errors that can be generated by XSetWMHints are BadWin- dow and BadAlloc. Use XGetWMHints to read the value of the window manager hints atom. The definition for this function is: XWMHints *XGetWMHints(display, w) Display *display; Window w; display Specifies the connection to the X server. December 18, 1987 - 295 - w Specifies the window ID. The XGetWMHints function reads the value of the window manager hints atom and returns either NULL if it fails (for example, if no WM_HINTS property was set on window w) or a pointer to a XWMHints structure if it succeeds. When fin- ished with this function, an application must free the space used for that structure by calling XFree. (See Section 2.4 for further information). The error that can be generated by XGetWMHints is BadWindow. 9.1.6. Setting and Getting Window Sizing Hints Xlib provides functions with which you can set or get window sizing hints. The functions discussed in this section use the XSizeHints structure: typedef struct { long flags; /* marks which fields in this structure are defined */ int x, y; int width, height; int min_width, min_height; int max_width, max_height; int width_inc, height_inc; struct { int x; /* numerator */ int y; /* denominator */ } min_aspect, max_aspect; } XSizeHints; The definitions for the flags field are: #define USPosition (1L << 0) /* user specified x, y */ #define USSize (1L << 1) /* user specified width, height */ #define PPosition (1L << 2) /* program specified position */ #define PSize (1L << 3) /* program specified size */ #define PMinSize (1L << 4) /* program specified minimum size */ #define PMaxSize (1L << 5) /* program specified maximum size */ #define PResizeInc (1L << 6) /* program specified resize increments */ #define PAspect (1L << 7) /* program specified min and max aspect ratios */ #define PAllHints (PPosition|PSize|PMinSize|PMaxSize|PResizeInc|PAspect) The x, y, width, and height elements describe a desired position and size for the window. To indicate that this information was specified by the user, set the USPosition and USSize flags. To indicate that it was specified by the application without any user involvement, set PPosition and PSize. This allows a window manager to know that the user specifically asked where the window should be placed or how the window should be sized and that the window manager does not have to rely the program's opinion. December 18, 1987 - 296 - The min_width and min_height elements specify the minimum size that the window can be for the application to be use- ful. The max_width and max_height elements specify the max- imum size. The width_inc and height_inc elements define an arithmetic progression of sizes (minimum to maximum) into which the window prefers to be resized. The min_aspect and max_aspect elements are expressed as ratios of x and y, and they allow an application to specify the range of aspect ratios it prefers. The next two functions set and read the WM_NORMAL_HINTS pro- perty. Use XSetNormalHints to set the size hints for a window in its normal state. The definition for this function is: void XSetNormalHints(display, w, hints) Display *display; Window w; XSizeHints *hints; display Specifies the connection to the X server. w Specifies the window ID. hints Specifies a pointer to the sizing hints for the window in its normal state. The XSetNormalHints function sets the size hints structure for the specified window. Applications use XSetNormalHints to inform the window manager of the size or position desir- able for that window. In addition, an application that wants to move or resize itself should call XSetNormalHints and specify its new desired location and size, instead of making direct X calls to move or resize. This is because window managers may ignore redirected configure requests, but they pay attention to property changes. To set size hints, an application not only must assign values to the appropriate elements in the hints structure, but it also must set the flags field of the structure to indicate which information is present and where it came from. A call to XSetNormalHints is meaningless, unless the flags field is set to indicate which elements of the struc- ture have been assigned values. The errors that can be generated by XSetNormalHints are BadWindow and BadAlloc. Use XGetNormalHints to return the size hints for a window in its normal state. The definition for this function is: December 18, 1987 - 297 - Status XGetNormalHints(display, w, hints_return) Display *display; Window w; XSizeHints *hints_return; display Specifies the connection to the X server. w Specifies the window ID. hints_returnReturns the sizing hints for the window in its normal state. The XGetNormalHints function returns in its last argument the size hints for a window in its normal state. It returns either a nonzero status if it succeeds or zero (0) if it fails (for example, the application specified no normal size hints for this window). The error that can be generated by XGetNormalHints is BadWindow. The next two functions set and read the WM_ZOOM_HINTS pro- perty. Use XSetZoomHints to set the value of the zoom hints atom. The definition for this function is: XSetZoomHints(display, w, zhints) Display *display; Window w; XSizeHints *zhints; display Specifies the connection to the X server. w Specifies the window ID. zhints Specifies a pointer to the zoom hints. Many window managers think of windows in three states: iconic, normal, or zoomed. The XSetZoomHints function pro- vides the window manager with information for the window in the zoomed state. The errors that can be generated by XSetZoomHints are BadWindow and BadAlloc. Use XGetZoomHints to read the value of the zoom hints atom. The definition for this function is: December 18, 1987 - 298 - Status XGetZoomHints(display, w, zhints_return) Display *display; Window w; XSizeHints *zhints_return; display Specifies the connection to the X server. w Specifies the window ID. zhints_returnReturns the zoom hints. The XGetZoomHints function returns in its last argument the size hints for a window in its zoomed state. It returns either a nonzero status if it succeeds or zero (0) if it fails (for example, the application specified no zoom size hints for this window). The error that can be generated by XGetZoomHints is BadWin- dow. Use XSetSizeHints to set the value of any property of type WM_SIZE_HINTS. The definition for this function is: XSetSizeHints(display, w, hints, property) Display *display; Window w; XSizeHints *hints; Atom property; display Specifies the connection to the X server. w Specifies the window ID. hints Specifies a pointer to the size hints. property Specifies the property atom. The XSetSizeHints function sets the XSizeHints structure for the named property and the specified window. This is used by XSetNormalHints and XSetZoomHints, and can be used to set the value of any property of type WM_SIZE_HINTS. Thus, it may be useful if other properties of that type get defined. The errors that can be generated by XSetSizeHints are BadWindow, BadAlloc and BadAtom. Use XGetSizeHints to read the value of any property of type WM_SIZE_HINTS. The definition for this function is: December 18, 1987 - 299 - Status XGetSizeHints(display, w, hints_return, property) Display *display; Window w; XSizeHints *hints_return; Atom property; display Specifies the connection to the X server. w Specifies the window ID. hints_returnReturns the size hints. property Specifies the property atom. XGetSizeHints returns the XSizeHints structure for the named property and the specified window. This is used by XGetNor- malHints and XGetZoomHints. It also can be used to retrieve the value of any property of type SIZE_HINTS. Thus, it may be useful if other properties of that type get defined. XGetSizeHints returns a nonzero status if a size hint was defined and zero (0) otherwise. The errors that can be generated by XGetSizeHints are BadWindow and BadAtom. 9.1.7. Setting and Getting Icon Sizing Hints Applications can cooperate with window managers by providing icons in sizes supported by a window manager. To communi- cate the supported icon sizes to the applications, a window manager should set the icon size property on the root win- dow. To find out what icon sizes a window manager supports, applications should read the icon size property from the root window. The functions discussed in this section set or read the WM_ICON_SIZE property. In addition, they use the XIconSize structure: typedef struct { int min_width, min_height; int max_width, max_height; int width_inc, height_inc; } XIconSize; The width_inc and height_inc elements define an arithmetic progression of sizes (minimum to maximum) that represent the supported icon sizes. Use XSetIconSizes to set the value of the icon size atom. The definition for this function is: December 18, 1987 - 300 - XSetIconSizes(display, w, size_list, count) Display *display; Window w; XIconSize *size_list; int count; display Specifies the connection to the X server. w Specifies the window ID. size_list Specifies a pointer to the size list. count Specifies the number of items in the size list. The XSetIconSizes function is used only by window managers to set the supported icon sizes. The errors that can be generated by XSetIconSizes are BadWindow and BadAlloc. Use XGetIconSizes to return the value of the icon sizes atom. The definition for this function is: Status XGetIconSizes(display, w, size_list_return, count_return) Display *display; Window w; XIconSize **size_list_return; int *count_return; display Specifies the connection to the X server. w Specifies the window ID. size_list_returnReturns a pointer to the size list. count_returnReturns the number of items in the size list. The XGetIconSizes function returns zero (0) if a window manager has not set icon sizes and nonzero status otherwise. This function should be called by an application which wants to find out what icon sizes would be most appreciated by the window manager under which the application is running. The application should then use XSetWMHints to supply the window manager with an icon pixmap or window in one of the sup- ported sizes. The error that can be generated by XGetIconSizes is BadWin- dow. December 18, 1987 - 301 - 9.1.8. Setting and Getting the Class of a Window Xlib provides functions to set and get the class of a win- dow. These functions set and read the WM_CLASS property. In addition, they use the XWMClass structure: typedef struct{ char *res_name; char *res_class; } XWMClassHint; The res_name member contains the application name, while the res_class member contains the application class. Note that the name set in this property may differ from the name set as WM_NAME. That is, WM_NAME specifies what should be displayed in the title bar and, therefore, may contain tem- poral information (for example, the name of a file currently in an editor's buffer). n the other hand, the name speci- fied as part of WM_CLASS is the formal name of the applica- tion that should be used when retrieving the application's resources from the resource database. Use XSetClassHint to set the class of a window. The defini- tion of this function is: XSetClassHint(display, w, class_hints) Display *display; Window w; XClassHint *class_hints; display Specifies the connection to the X server. w Specifies the window ID. class_hintsSpecifies a pointer to a XWMClassHint structure that is to be used. The XSetClassHint functions sets the class hint for the specified window. The errors that can be generated by XSetClassHint are BadWindow and BadAlloc. Use XGetClassHint to get the class of a window. The defin- ition of this function is: Status XGetClassHint(display, w, class_hints_return) Display *display; Window w; XClassHint *class_hints_return; December 18, 1987 - 302 - display Specifies the connection to the X server. w Specifies the window ID. class_hints_returnReturns the XWMClassHints structure. The XGetClassHint function obtains the class of the speci- fied window. The error that can be generated by XGetClassHint is BadWin- dow. 9.1.9. Setting and Getting the Transient Property An application may want to indicate to the window manager that a transient top-level window (for example, a dialog box) is not really a full-fledged window. Rather, it is operating on behalf of (or is transient for) another window. To do so, the application would set the WM_TRANSIENT_FOR property of the dialog box to be the window handle of its main window. Some window managers may use this information to unmap an application's dialog boxes (for example, when the main application window gets iconified). The functions discussed in this section set and read the WM_TRANSIENT_FOR property. Use XSetTransientForHint to set the WM_TRANSIENT_FOR pro- perty for a window. The definition of this function is: XSetTransientForHint(display, w, prop_window) Display *display; Window w; Window prop_window; display Specifies the connection to the X server. w Specifies the window ID. prop_windowSpecifies the window ID that the WM_TRANSIENT_FOR property is to be set to. The XSetTransientForHint set the WM_TRANSIENT_FOR atom of the specified window to the specified prop_window. The errors that can be generated by XSetTransientForHint are BadWindow and BadAlloc. Use XGetTransientForHint to get the WM_TRANSIENT_FOR value for a window. The definition of this function is: December 18, 1987 - 303 - Status XGetTransientForHint(display, w, prop_window_return) Display *display; Window w; Window *prop_window_return; display Specifies the connection to the X server. w Specifies the window ID. prop_window_returnReturns the WM_TRANSIENT_FOR property of the specified window. The XGetTransientForHint function obtains the WM_TRANSIENT_FOR property for the specified window. The error that can be generated by XGetTransientForHint is BadWindow. 9.2. Manipulating Standard Colormaps Applications with color palettes, smooth-shaded drawings, or digitized images demand large numbers of colors. In addi- tion, these application often require an efficient mapping from color triples to pixel values that display the appropriate colors. As an example, consider a 3D display program that wants to draw a smoothly shaded sphere. At each pixel in the image of the sphere, the program computes the intensity and color of light reflected back to the viewer. The result of each com- putation is a triple of red, green, and blue coefficients in the range 0.0 to 1.0. To draw the sphere, the program needs a colormap that provides a large range of uniformly distri- buted colors. The colormap should be arranged so that the program can convert its RGB triples into pixel values very quickly, because drawing the entire sphere will require many such conversions. On many current workstations the display is limited to 256 or fewer colors. Applications must allocate colors carefully not only to make sure they cover the entire range they need but also to make use of as many of the available colors as possible. On a typical X display, many applications are active at once. Most workstations have only one hardware lookup table for colors, so only one application colormap can be installed at a given time. The application using the installed colormap is displayed correctly, while the other applications ``go technicolor'' and are displayed with false colors. As another example, consider a user who is running an image processing program to display earth-resources data. The image processing program needs a colormap set up with 8 December 18, 1987 - 304 - reds, 8 greens, and 4 blues (total of 256 colors). Because some colors are already in use in the default colormap, the image processing program allocates and installs a new color- map. The user decides to alter some of the colors in the image. He invokes a color palette program to mix and choose colors. The color palette program also needs a colormap with 8 reds, 8 greens, and 4 blues, so, just as the image-processing pro- gram, it must allocate and install a new colormap. Because only one colormap can be installed at a time, the color palette may be displayed incorrectly whenever the image-processing program is active. Conversely, whenever the palette program is active, the image may be displayed incorrectly. The user can never match or compare colors in the palette and image. Contention for colormap resources can be reduced if applications with similar color needs share colormaps. As another example, the image processing program and the color palette program could share the same colormap if there existed a convention that described how the colormap was set up. Whenever either program was active, both would be displayed correctly. The standard colormap properties define a set of commonly used colormaps. Applications that share these colormaps and conventions display true colors more often and provide a better interface to the user. 9.2.1. Standard Colormaps Standard colormaps allow applications to share commonly used color resources. This allows many applications to be displayed in true colors simultaneously, even when each application needs an entirely filled colormap. Several standard colormaps are described. Usually, these colormaps are created by a window manager. Applications should use the standard colormaps if they already exist. If the standard colormaps do not exist, applications should create new standard colormaps. The XStandardColormap structure contains: December 18, 1987 - 305 - typedef struct { Colormap colormap; unsigned long red_max; unsigned long red_mult; unsigned long green_max; unsigned long green_mult; unsigned long blue_max; unsigned long blue_mult; unsigned long base_pixel; } XStandardColormap; The colormap field is the ID of a colormap created by the XCreateColormap function. The red_max, green_max, and blue_max fields give the maximum red, green, and blue values, respectively. Each color coefficient ranges from zero (0) to its max, inclusive. For example, a common color- map allocation is 3/3/2 (3 planes for red, 3 planes for green, and 2 planes for blue). This colormap would have red_max = 7, green_max = 7, and blue_max = 3. An alternate allocation that uses only 216 colors is red_max = 5, green_max = 5, and blue_max = 5. The red_mult, green_mult, and blue_mult fields give the scale factors used to compose a full pixel value. (See the discussion of the base_pixel field for further information.) For a 3/3/2 allocation red_mult might be 32, green_mult might be 4, and blue_mult might be 1. For a 6-colors-each allocation, red_mult might be 36, green_mult might be 6, and blue_mult might be 1. The base_pixel field gives the base pixel value used to com- pose a full pixel value. Usually, the base_pixel is obtained from a call to the XAllocColorPlanes function. Given integer red, green, and blue coefficients in their appropriate ranges, one then can compute a corresponding pixel value by using the following expression. r * red_mult + g * green_mult + b * blue_mult + base_pixel For gray-scale colormaps, only the colormap, red_max, red_mult, and base_pixel fields are defined. The other fields are ignored. To compute a gray-scale pixel value, use the following expression. gray * red_mult + base_pixel The properties containing the XStandardColormap information have the type RGB_COLOR_MAP. December 18, 1987 - 306 - 9.2.2. Standard Colormap Properties and Atoms Several standard colormaps are available. Each standard colormap is defined by a property, and each such property is identified by an atom. The following list names the atoms and describes the colormap associated with each one. RGB_DEFAULT_MAPThis atom names a property. The value of the property is an XStandardColormap. The property defines an RGB subset of the system default colormap. Some applications only need a few RGB colors and may be able to allocate them from the system default colormap. This is the ideal situation, since the fewer colormaps are active in the system the more applications are displayed with correct colors at all times. A typical allocation for the RGB_DEFAULT_MAP on 8-plane displays is 6 reds, 6 greens, and 6 blues. This gives 216 uniformly distributed colors (6 intensities of 36 different hues) and still leaves 40 elements of a 256-element colormap available for special-purpose colors for text, borders, and so on. RGB_BEST_MAP This atom names a property. The value of the pro- perty is an XStandardColormap. The property defines the best RGB colormap avail- able on the display. (Of course, this is a sub- jective evaluation.) Many image processing and 3D applications need to use all available colormap cells and distribute as many perceptually distinct colors as possible over those cells. This implies that there may be more green values available than red, as well as more green or red than blue. On an 8-plane pseudocolor display, RGB_BEST_MAP is a 3/3/2 allocation. On a 24-plane directcolor display, RGB_BEST_MAP is an 8/8/8 allocation. On other displays, RGB_BEST_MAP is purely up to the implementor of the display. RGB_RED_MAP RGB_GREEN_MAP RGB_BLUE_MAPThese atoms name properties. The values of the properties are XStandardColormaps. The properties define all-red, all-green, and all-blue colormaps, respectively. These maps are used by applications that want to make color- separated images. For example, a user might December 18, 1987 - 307 - generate a full-color image on an 8-plane display both by rendering an image three times (once with high color resolution in red, once with green, and once with blue) and by multiply-exposing a single frame in a camera. RGB_GRAY_MAPThis atom names a property. The value of the property is an XStandardColormap. The property describes the best gray-scale colormap avail- able on the display. As previously mentioned, only the colormap, red_max, red_mult, and base_pixel fields of the XStandardColormap structure are used for gray-scale color- maps. 9.2.3. Getting and Setting the XStandardColormap Structure Use XGetStandardColormap to get the XStandardColormap struc- ture associated with one of the described atoms. The defini- tion for this function is: Status XGetStandardColormap(display, w, cmap_return, property) Display *display; Window w; XStandardColormap *cmap_return; Atom property; /* RGB_BEST_MAP, etc. */ display Specifies the connection to the X server. w Specifies the window ID. cmap_returnReturns the colormap associated with the speci- fied atom. property Specifies the property atom. The XGetStandardColormap function returns the colormap definition associated with the atom supplied as the property argument. For example, to fetch the standard gray-scale colormap for a display, you use XGetStandardColormap with the following syntax: XGetStandardColormap(dpy, DefaultRootWindow(dpy), &cmap, RGB_GRAY_MAP); Once you have fetched a standard colormap, you can use it to convert RGB values into pixel values. For example, given an XStandardColormap structure and floating point RGB coeffi- cients in the range 0.0 to 1.0, you can compose pixel values with the following C expression: December 18, 1987 - 308 - pixel = base_pixel + ((unsigned long) (0.5 + r * red_max)) * red_mult + ((unsigned long) (0.5 + g * green_max)) * green_mult + ((unsigned long) (0.5 + b * blue_max)) * blue_mult; The use of addition rather than logical OR for composing pixel values permits allocations where the RGB value is not aligned to bit boundaries. The errors that can be generated by XGetStandardColormap are BadWindow and BadAtom. Use XSetStandardColormap to create or change a standard colormap. The definition for this function is: void XSetStandardColormap(display, w, cmap, property) Display *display; Window w; XStandardColormap *cmap; Atom property; /* RGB_BEST_MAP, etc. */ display Specifies the connection to the X server. w Specifies the window ID. cmap Specifies the color map ID. property Specifies the property atom. The XSetStandardColormap function usually is only used by window managers. To create a standard colormap, follow this procedure: 1. Grab the server. 2. See if the property is on the property list of the root window for the display. 3. If the desired property is not present, do the follow- ing: o Create a colormap (not required for RGB_DEFAULT_MAP) o Determine the color capabilities of the display. o Call XAllocColorPlanes or XAllocColorCells to allocate cells in the colormap. o Call XStoreColors to store appropriate color values in the colormap. December 18, 1987 - 309 - o Fill in the descriptive fields in the property. o Attach the property to the root window. 4. Ungrab the server. The errors that can be generated by XSetStandardColormap are BadWindow, BadAtom, and BadAlloc. December 18, 1987 - 310 - Chapter 10 Application Utility Functions Chapter 10 - Application Utility Functions Once you have initialized the X system, you can use the Xlib utility func- tions to: o Handle keyboard events o Obtain the X environment defaults o Parse the window geometry o Parse the hardware colors o Generate regions o Manipulate regions o Use the cut and paste buffers o Determine the appropriate visual o Manipulate images o Manipulate bitmaps o Use the resource manager o Use the context manager Note As a group, the functions discussed in this chapter provide the functionality that is fre- quently needed and spans toolkits. These func- tions do not generate actual protocol requests to the server. 10.1. Keyboard Utility Functions Xlib provides with which you manipulate keyboard event or can determine information about a keysym. This section discusses: o Keyboard event functions December 18, 1987 - 311 - o Keysym classification macros 10.1.1. Keyboard Event Functions The X server does not predefine the keyboard to be ASCII characters. It is often useful to know that the ``a'' key was just pressed or possibly that it was just released. When a key is pressed or released, the X server sends key- board events to client programs. The structures associated with keyboard events contain a keycode member that assigns a number to each physical key on the keyboard. See Section 8.4.1 for a discussion of keyboard event processing. See Section 7.9 for information on how to manipulate the key- board encoding. Because keycodes are completely arbitrary and may differ from server to server, client programs wanting to deal with ASCII text, for example, must explicitly convert the keycode value into ASCII. The transformation of keycodes to ASCII or other character sets is arbitrary. Therefore, Xlib pro- vides functions to help you customize the keyboard layout. Keyboards often differ dramatically, so writing code that presumes the existence of a particular key on the main key- board will create portability problems. It may also be dif- ficult to receive KeyRelease events on certain X server implementations because of hardware or software restric- tions. Keyboard events are usually sent to the smallest enclosing window which is interested in that type of event underneath the pointer's position. It is also possible to assign the keyboard input focus to a specific window. When the input focus is attached to a window, keyboard events will go to the client which has selected input on that window rather than the window under the pointer. This section discusses the functions with which you can query the keyboard, look up the keyboard mappings, rebind the keyboard, or use an alternate keyboard mapping file. Note Some implementations cannot support KeyRelease events. You should think seriously before design- ing software that takes advantage of KeyRelease events if you are concerned about wide portabil- ity, though there are some applications that can exploit KeyRelease events to provide superior user interfaces. You should also be very careful when selecting which keys may be used in such applica- tions. It may be impossible to guarantee the existence of a set of keys on all keyboards with the probable exception of a-z, spacebar, and car- riage return. December 18, 1987 - 312 - Use XLookupKeysym to look up the KeySyms. The definition for this function is: KeySym XLookupKeysym(event_key, index) XKeyEvent *event_key; int index; event_key Specifies the key event that is to be used. This event is either a KeyPress event or a KeyRelease event. index Specifies the index into the KeySyms table. The XLookupKeysym function uses a given keyboard event and the index you specified to return the KeySym from the list that corresponds to the keycode member in the XKeyPressedEvent or XKeyReleasedEvent structure. Use XRefreshKeyboardMapping to refresh the stored modifier and keymap information. The definition for this function is: XRefreshKeyboardMapping(event_map) XMappingEvent *event_map; event_map Specifies the mapping event that is to be used. The XRefreshKeyboardMapping function refreshes the stored modifier and keymap information. You usually call this function when a MappingNotify event occurs. The result is to update a client application's knowledge of the keyboard. See Section 8.4.7.7 for information on MappingNotify event processing. Use XLookupString to map a key event to an ASCII string. The definition for this function is: int XLookupString(event_struct, buffer_return, bytes_buffer, keysym_return, status_return) XKeyEvent *event_struct; char *buffer_return; int bytes_buffer; KeySym *keysym_return; XComposeStatus *status_return; event_structSpecifies the key event structure to be used: XKeyPressedEvent or XKeyReleasedEvent. buffer_returnReturns the translated characters. December 18, 1987 - 313 - bytes_bufferSpecifies the length of the buffer. No more than bytes_buffer of translation are returned. keysym_returnIf this argument is not NULL, returns the keysym computed from the event. status_returnSpecifies either a pointer to the XCompose structure that is to contain compose key state information and that allows compose key processing to take place, or NULL. The XLookupString function is a convenience routine that can be used to map a key event to an ASCII string, using the modifier bits in the key event to deal with shift, lock, and control. It returns the translated string into the user's buffer. It also detects any rebound keysyms (see XRe- bindKeysym) and returns the specified bytes. XLookupString returns, as its value, the length of the string stored in the tag buffer. If the lock modifier has a caps_lock key associated with it, XLookupString interprets the lock modif- ier to perform caps lock processing. Use XRebindKeysym to rebind the meaning of a keysym for a client. The definition for this function is: XRebindKeysym(display, keysym, list, mod_count, string, bytes_string) Display *display; KeySym keysym; KeySym *list; int mod_count; unsigned char *string; int bytes_string; display Specifies the connection to the X server. keysym Specifies the keysym to be rebound. list Specifies a pointer to an array of keysyms that are being used as modifiers. mod_count Specifies the number of modifiers in the modifier list. string Specifies a pointer to the string that is to be returned by XLookupString. bytes_stringSpecifies the length of the string. The XRebindKeysym function can be used to rebind the meaning of a keysym for the client. It does not redefine the key- code in the X server but merely provides an easy way for long strings to be attached to keys. XLookupString returns December 18, 1987 - 314 - this string when the appropriate set of modifier keys are pressed and when the keysym would have been used for the translation. Note that you can rebind a keysym that may not exist. Use XStringToKeysym to convert the name of the keysym to the keysym code. The definition for this function is: KeySym XStringToKeysym(string) char *string; string Specifies the name of the keysym that is to be converted. Valid keysym names are listed in <X11/keysymdef.h>. If the specified string does not match a valid keysym, XStringToKeysym returns NoSymbol. Use XKeysymToString to convert a keysym code to the name of the keysym. The definition for this function is: char *XKeysymToString(keysym_str) KeySym keysym_str; keysym_strSpecifies the keysym that is to be converted. The returned string is in a static area and must not be modified. If the specified keysym is not defined, XKeysym- ToString returns a NULL. Use XKeycodeToKeysym to convert a key code to a defined keysym. The definition for this function is: KeySym XKeycodeToKeysym(display, keycode, index_return) Display *display; KeyCode keycode; int index_return; display Specifies the connection to the X server. keycode Specifies the keycode. index_returnReturns the element of keycode vector. XKeycodeToKeysym uses internal Xlib tables, which already have converted alphabetic upper case to lowercase, and returns the keysym defined for the specified keycode and the element of the keycode vector. December 18, 1987 - 315 - Use XKeysymToKeycode to convert a keysym to the appropriate keycode. The definition for this function is: KeyCode XKeysymToKeycode(display, keysym_kcode) Display *display; Keysym keysym_kcode; display Specifies the connection to the X server. keysym_kcodeSpecifies the keysym that is to be searched for. If the specified keysym is not defined for any keycode, XKeysymToKeycode returns zero (0). 10.1.2. Keysym Classification Macros You may want to test if a keysym of the defined set (XK_MISCELLANY) is, for example, on the key pad or the func- tion keys. You can use the keysym macros to perform the following tests. IsKeypadKey(keysym) Returns True if the keysym is on the key pad. IsCursorKey(keysym) Returns True if the keysyum is on the cursor key. IsPFKey(keysym) Returns True if the keysyum is on the PF keys. IsFunctionKey(keysym) Returns True if the keysyum is on the function keys. IsMiscFunctionKey(keysym) Returns True if the keysyum is on the miscellaneous function keys. December 18, 1987 - 316 - IsModifierKey(keysym) Returns True if the keysyum is on the modifier keys. 10.2. Obtaining the X Environment Defaults A program often needs a variety of options in the X environ- ment (for example, fonts, colors, mouse, background, text, cursor). Specifying these options on the command line is inefficient and unmanageable because individual users have a variety of tastes with regard to window appearance. XGetDe- fault makes it easy to find out the fonts, colors, and other environment defaults favored by a particular user. Defaults are usually loaded onto a property on the root window at login. It merges any additional defaults from a file in the user's home directory. On a UNIX-based system, it uses ~/.Xdefaults. See the X manual page for details of its for- mat. This is a simple interface for clients not wishing to use the X toolkit or the more elaborate interfaces provided by the resource manager discussed in section 10.11. The strings returned by XGetDefault are owned by Xlib and should not be modified or freed by the client. The defini- tion for this function is: char *XGetDefault(display, program, option) Display *display; char *program; char *option; display Specifies the connection to the X server. program Specifies the program name for the Xlib defaults. You must pass the program name in with the program argument (usually argv[0]). option Specifies the option name. XGetDefault returns the value NULL if the option name speci- fied in this argument does not exist for the program. 10.3. Parsing the Window Geometry Xlib provides functions with which you can parse the window geometry. Use XParseGeometry to parse standard window geometry strings. The definition for XParseGeometry is: December 18, 1987 - 317 - int XParseGeometry(parsestring, x_return, y_return, width_return, height_return) char *parsestring; int *x_return, *y_return; int *width_return, *height_return; parsestringSpecifies the string you want to parse. x_return y_return Returns the xoffset and yoffset determined. width_return height_returnReturn the width and height determined. By convention, X applications use a standard string to indi- cate window size and placement. XParseGeometry makes it easier to conform to this standard because it allows you to parse the standard window geometry. Specifically, this function lets you parse strings of the form: =<width>x<height>{+-}<xoffset>{+-}<yoffset> The items in this form map into the arguments associated with this function. The XParseGeometry function returns a bitmask that indicates which of the four values (width, height, xoffset, and yoffset) were actually found in the string and that indi- cates whether the x and y values are negative. By conven- tion, -0 is not equal to +0, because the user needs to be able to say "position the window relative to the right or bottom edge." For each value found, the corresponding argu- ment is updated. For each value not found, the argument is left unchanged. The bits are represented by these con- stants: XValue, YValue, WidthValue, HeightValue, XNegative, YNegative and are defined in <X11/Xutil.h>. They will be set whenever one of the values are defined or signs are set. If the function returns either the XValue or YValue flag, you should place the window at the requested position. The border width (bwidth), size of the increments width and height (typically font width and height), and any additional interior space (xadd and yadd) are passed in to make it easy to compute the resulting size. It is not normally used by user programs, which typically use the XCreateWindow or XCreateSimpleWindow function to create the window. Use XGeometry to parse window geometry given an argument and a default position. The definition for this function is: December 18, 1987 - 318 - int XGeometry(display, screen, position, default, bwidth, fwidth, fheight, xadder, yadder, x_return, y_return, width_return, height_return) Display *display; int screen; char *position, *default; unsigned int bwidth; unsigned int fwidth, fheight; int xadder, yadder; int *x_return, *y_return; int *width_return, *height_return; display Specifies the connection to the X server. screen Specifies the screen. position default Specify the geometry specifications. bwidth Specifies the border width. fheight fwidth Specify the font height and width in pixels (increment size). xadder yadder Specify additional interior padding needed in the window. x_return y_return Returns the xoffset and yoffset determined. width_return height_returnReturn the width and height determined. The XGeometry function returns the position the window should be placed given a position and a default position. XGeometry determines the placement of a window using the current format to position windows. Given a fully qualified default geometry specification and, possibly, an incom- pletely specified geometry specification, it will return a bitmask value as defined above in the XParseGeometry call. 10.4. Parsing the Color Specifications Use XParseColor to parse color values. The definition for this function is: Status XParseColor(display, cmap, spec, screen_def_return) Display *display; Colormap cmap; char *spec; XColor *screen_def_return; December 18, 1987 - 319 - display Specifies the connection to the X server. cmap Specifies the color map ID. spec Specifies the color name string. Uppercase and lowercase characters are acceptable. screen_def_returnReturns the values actually used in the color map. The XParseColor function provides a simple way to create a standard user interface to color. It takes a string specif- ication of a color, typically from a command line or XGetDe- fault option, and returns the corresponding red, green, and blue values that are suitable for a subsequent call to XAl- locColor or XStoreColor. The color can be specified either as a color name (as in XAllocNamedColor) or as an initial sharp sign character following by a numeric specification, in one of the following formats: #RGB (4 bits each) #RRGGBB (8 bits each) #RRRGGGBBB (12 bits each) #RRRRGGGGBBBB (16 bits each) The R, G, and B represent single hexadecimal digits (upper or lower case). When fewer than 16 bits each are specified, they represent the most significant bits of the value. For example, #3a7 is the same as #3000a0007000. The colormap is used only to determine which screen to look up the color on. For example, you can use the screen's default colormap. This routine will fail and return zero (0) status either if the initial character is a sharp sign, but the string other- wise fails to fit of the above formats, or if the initial character is not a sharp sign and the named color does not exist in the server's database. The error that can be generated by XParseColor is BadColor. 10.5. Generating Regions Regions are arbitrary collections of pixels. Xlib provides functions for manipulating regions. The opaque type Region is defined in <X11/Xutil.h>. Use XPolygonRegion to generate a region from points. The definition for this function is: Region XPolygonRegion(n, points, fill_rule) int n; XPoint points[]; int fill_rule; December 18, 1987 - 320 - n Specifies the number of points in the polygon. points Specifies an array of points. fill_rule Specifies the fill rule you want to set for the specified graphics context. You can pass one of these constants: EvenOddRule or WindingRule. The XPolygonRegion function returns a region defined by the points array. See XCreateGC in Section 5.3 for an explana- tion of fill_rule. Use XClipBox to generate the smallest enclosing rectangle in rect. The definition for this function is: XClipBox(r, rect) Region r; XRectangle *rect; r Specifies the region. This is the region in which the rectangle is located. rect Specifies the rectangle. This is the rectangle in which the smallest enclosing rectangle is gen- erated. The XClipBox function generates the smallest enclosing rec- tangle in the specified rectangle that is located in the specified region. 10.6. Manipulating Regions Xlib provides functions with which you can manipulate regions. This section discusses how to: o Create, copy, or destroy regions o Move or shrink regions o Compute with regions o Determine if regions are empty or equal o Locate a point or rectangle in a region 10.6.1. Creating, Copying, or Destroying Regions Xlib provides functions with which you can create, copy, or destroy a region. Use XCreateRegion to create a new empty region. The December 18, 1987 - 321 - definition for this function is: Region XCreateRegion() Use XSetRegion to set the graphics contexts to the specified region. The definition for this function is: XSetRegion(display, gc, r) Display *display; GC gc; Region r; display Specifies the connection to the X server. gc Specifies the graphics context. r Specifies the region. This is the region in which you want to set the specified graphics context. The XSetRegion function sets the clip mask in the graphics contexts to the specified region. Once is is set in the GC, the region can be destroyed. Use XDestroyRegion to deallocate the storage associated with a specified region. The definition for this function is: XDestroyRegion(r) Region r; r Specifies the region. 10.6.2. Moving or Shrinking Regions Xlib provides functions with which you can move or shrink regions. Use XOffsetRegion to move the specified region by a speci- fied amount. The definition for this function is: XOffsetRegion(r, dx, dy) Region r; int dx, dy; r Specifies the region. December 18, 1987 - 322 - dx dy Specify the x and y coordinates. These coordi- nates define the amount by which you want to move the specified region. Use XShrinkRegion to reduce the specified region by a speci- fied amount. The definition for this function is: XShrinkRegion(r, dx, dy) Region r; int dx, dy; r Specifies the region. dx dy Specify the x and y coordinates. These coordi- nates define the amount by which you want to shrink the specified region. Positive values shrink the size of the region, while nega- tive values expand the region. 10.6.3. Computing with Regions Xlib provides functions with which you can compute the intersection, union, or results of two regions. Use XIntersectRegion to compute the intersection of two regions. The definition for this function is: XIntersectRegion(sra, srb, dr) Region sra, srb, dr; sra srb Specify the two regions with which you want to perform the computation. dr Stores the result of the computation. Use XUnionRegion to compute the union of two regions. The definition for this function is: XUnionRegion(sra, srb, dr) Region sra, srb, dr; sra December 18, 1987 - 323 - srb Specify the two regions with which you want to perform the computation. dr Stores the result of the computation. Use XSubtractRegion to subtract two regions. The definition for this function is: XSubtractRegion(sra, srb, dr) Region sra, srb, dr; sra srb Specify the two regions with which you want to perform the computation. dr Stores the result of the computation. Use XXorRegion to calculate the difference between the union and intersection of two regions. The definition for this function is: XXorRegion(sra, srb, dr) Region sra, srb, dr; sra srb Specify the two regions with which you want to perform the computation. dr Stores the result of the computation. 10.6.4. Determining If Regions Are Empty or Equal Xlib provides functions with which you can determine if regions are empty or equal. Use XEmptyRegion to determine if the specified region is empty. The definition for this function is: int XEmptyRegion(r) Region r; r Specifies the region. The XEmptyRegion function returns nonzero if the region is empty. Use XEqualRegion to determine if two regions have the same December 18, 1987 - 324 - offset, size, and shape. The definition for this function is: int XEqualRegion(r1, r2) Region r1, r2; r1 r2 Specify the two regions. These are the regions you want to determine have the same offset, size, and shape. The XEqualRegion function returns nonzero if the two regions are identical (that is, they have the same offset, size, and shape). 10.6.5. Locating a Point or a Rectangle in a Region Xlib provides functions with which you can determine if a point or a rectangle is contained in a region. Use XPointInRegion to determine if a specified point resides in a specified region. The definition for this function is: int XPointInRegion(r, x, y) Region r; int x, y; r Specifies the region. x y Specify the x and y coordinates. These define the coordinates of the point. The XPointInRegion function returns nonzero if the point x, y is contained in the region r. Use XRectInRegion to determine if a specified rectangle resides in the specified region. The definition for this function is: int XRectInRegion(r, x, y, width, height) Region r; int x, y; unsigned int width, height; r Specifies the region. December 18, 1987 - 325 - x y Specify the x and y coordinates. These define the coordinates of the point. width height Specify the width and height. These specify the rectangle in which you want to determine the point resides. The XRectInRegion function returns RectangleIn if the rec- tangle is entirely in the specified region, RectangleOut if the rectangle is entirely out of the specified region, and RectanglePart if the rectangle is partially in the specified region. 10.7. Using the Cut and Paste Buffers Xlib provides functions with which you can use cut and paste buffers for programs using this form of communications. See also the sections on selections, which are a more useful mechanism for interchanging data between clients, as typed information can be exchanged. X provides areas of memory in which bytes can be stored for implementing cut and paste between windows (implemented by use of properties on the first root window of the display). It is up to applications to agree on how to represent the data in the buffers. The data is most often ISO Latin 1 text. The atoms for eight such buffers are provided, which can be accessed as a ring or as explicit buffers (numbered 0 through 7). These buffers are typically used by either XYO applications or Andrew applications. We encourage new applications to share data by using selections. See Section 4.4 for further information. Use XStoreBytes to store data in cut buffer 0. The defini- tion for this function is: XStoreBytes(display, bytes, nbytes) Display *display; char bytes[]; int nbytes; display Specifies the connection to the X server. bytes Specifies the string of bytes you want stored. The byte string is not necessarily ASCII or null- terminated. nbytes Specifies the number of bytes of the bytes argu- ment that you want stored. The XStoreBytes function returns the number of bytes to be December 18, 1987 - 326 - stored to the nbytes argument. Note that the cut buffer's contents need not be text, so null bytes are not special. The cut buffer's contents may be retrieved later by any client calling XFetchBytes. The errors that can be generated by XStoreBytes are BadWin- dow and BadAlloc. Use XStoreBuffer to store data in a specified cut buffer. The definition for this function is: XStoreBuffer(display, bytes, nbytes, buffer) Display *display; char bytes[]; int nbytes; int buffer; display Specifies the connection to the X server. bytes Specifies the string of bytes you want stored. The byte string is not necessarily ASCII or null- terminated. nbytes Specifies the number of bytes of the bytes argu- ment that you want stored. buffer Specifies the buffer in which you want to store the byte string. The errors that can be generated by XStoreBuffer are BadWin- dow, BadAtom, and BadAlloc. Use XFetchBytes to return data from cut buffer 0. The definition for this function is: char *XFetchBytes(display, nbytes_return) Display *display; int *nbytes_return; display Specifies the connection to the X server. nbytes_returnReturns the number of bytes in the string in the buffer. XFetchBytes returns the number of bytes in this argument. If there is no data in the buffer, the value zero (0) is returned to this argument. The XFetchBytes function returns the number of bytes in the nbytes argument, if the buffer contains data. Otherwise, the function returns NULL and sets nbytes to 0. The December 18, 1987 - 327 - XFetchBytes function returns the number of bytes in the nbytes argument, if the buffer contains data. Otherwise, the function returns NULL and sets nbytes to zero (0). The appropriate amount of storage is allocated and the pointer returned. The client must free this storage when finished with it by calling XFree. (See Section 2.4 for further information.) Note that the cut buffer does not necessarily contain text, so it may contain embedded null bytes and may not terminate with a null byte. The error that can be generated by XFetchBytes is BadWindow. Use XFetchBuffer to return data from a specified cut buffer. The definition for this function is: char *XFetchBuffer(display, nbytes_return, return_buffer) Display *display; int *nbytes_return; int return_buffer; display Specifies the connection to the X server. nbytes_returnReturns the number of bytes in the string in the buffer. return_bufferSpecifies which buffer you want to stored data to be returned from. The XFetchBuffer function returns the value zero (0) to the nbytes argument if there is no data in the buffer. The error that can be generated by XFetchBuffer is BadValue. Use XRotateBuffers to rotate the cut buffers. The defini- tion for this function is: XRotateBuffers(display, rotate) Display *display; int rotate; display Specifies the connection to the X server. rotate Specifies how much to rotate the cut buffer. The XRotateBuffers function rotates the cut buffers, such that buffer 0 becomes buffer n, buffer 1 becomes n+1 mod 8, and so on. This cut buffer numbering is global to the display. Note that XRotateBuffers will generate an error if any of the eight buffer have not been created. December 18, 1987 - 328 - The errors that can be generated by XRotateBuffers are BadWindow, BadAtom, and BadMatch. 10.8. Determining the Appropriate Visual A single display may support multiple screens. Each screen can have several different visual types supported at dif- ferent depths. You can use the functions described in this section to determine which visual to use for your applica- tion. The functions in this section use the XVisualInfo structure, which can be found in <X11/Xutil.h>. typedef struct { Visual *visual; VisualID visualid; int screen; unsigned int depth; int class; unsigned long red_mask; unsigned long green_mask; unsigned long blue_mask; int colormap_size; int bits_per_rgb; } XVisualInfo; The definitions used for the visual information mask (vinfo_mask) are: #define VisualNoMask 0x0 #define VisualIDMask 0x1 #define VisualScreenMask 0x2 #define VisualDepthMask 0x4 #define VisualClassMask 0x8 #define VisualRedMaskMask 0x10 #define VisualGreenMaskMask 0x20 #define VisualBlueMaskMask 0x40 #define VisualColormapSizeMask0x80 #define VisualBitsPerRGBMask 0x100 #define VisualAllMask 0x1FF Use XGetVisualInfo to obtain a list of visual information structures that match a specified template. The definition for this function is: XVisualInfo *XGetVisualInfo(display, vinfo_mask, vinfo_template, nitems_return) Display *display; long vinfo_mask; XVisualInfo *vinfo_template; int *nitems_return; December 18, 1987 - 329 - display Specifies the connection to the X server. vinfo_maskSpecifies the visual mask value. vinfo_templateSpecifies the visual attributes that are to be used in matching the visual structures. nitems_returnReturns the number of matching visual struc- tures. The XGetVisualInfo function returns a list of visual struc- tures that match the attributes specified by the template argument. If no visual structures match the template using the specified vinfo_mask, XGetVisualInfo returns a NULL. Use XFree to free the data returned by this function. (See Section 2.4 for further information.) Use XMatchVisualInfo to obtain the visual information that matches the specified depth and class of the screen. The definition for this function is: Status XMatchVisualInfo(display, screen, depth, class, vinfo_return) Display *display; int screen; int depth; int class; XVisualInfo *vinfo_return; display Specifies the connection to the X server. screen Specifies the screen. depth Specifies the depth of the screen. class Specifies the class of the screen. vinfo_returnReturns the match visual information. The XMatchVisualInfo function returns the visual information for a visual that matches the specified depth and class for a screen. Because multiple visuals that match the specified depth and class can exist, the exact visual chosen is unde- fined. If a visual is found, this function returns True, and the information on the visual is returned to the vinfo argument. Otherwise, when a visual is not found, it returns False. 10.9. Manipulating Images Xlib provides several functions that perform basic opera- tions on images. All operations on images are defined using an XImage structure, as defined in <X11/Xlib.h>. Because December 18, 1987 - 330 - the number of different types of image formats can be very large, this hides details of image storage properly from applications. This section describes the functions for generic operations on images. Manufacturers can provide very fast implementa- tions of these for the formats frequently encountered on their hardware. These functions are neither sufficient nor desirable to use for general image processing. Rather, they are here to provide minimal functions on screen format images. The basic operations for getting and putting images are XGetImage and XPutImage. See Chapter 6 for further information about these functions. Note The functions to read and write images to and from disk files are not, as yet, defined. This whole section probably needs work and elaboration. Suggestions are gratefully solicited. Most of the fields are defined in the core protocol to specify hardware variants, bit and byte ordering you may encounter across manufacturers. The XImage structure describes an image as it exists in the client's memory. The user may request that some of the members such as height, width, and xoffset be changed when the image is sent to the server (that is, the user may send a subset of the image). Other members (for example, byte order, bitmap_unit, and so forth) are characteristics of both the image and of the server. If these members differ between the image and the server, XPutImage makes the appropriate conversions. See Chapter 6 for information about XPutImage. If the image is formatted as an XYPixmap, that is the format member is set to the constant XYPixmap, the first byte of the first line of plane n must be located at the address (data + (n * height * bytes_per_line)). Use XCreateImage to allocate sufficient memory for an XImage structure. The definition for this function is: December 18, 1987 - 331 - XImage *XCreateImage(display, visual, depth, format, offset, data, width, height, bitmap_pad, bytes_per_line) Display *display; Visual *visual; unsigned int depth; int format; int offset; char *data; unsigned int width; unsigned int height; int bitmap_pad; int bytes_per_line; display Specifies the connection to the X server. visual Specifies a pointer to the visual. depth Specifies the depth of the image. format Specifies the format for the image. You can pass one of these constants: XYPixmap or ZPixmap. offset Specifies the number of pixels to ignore at the beginning of the scanline. This permits the rapid displaying of the image without requiring each scanline to be shifted into position. data Specifies a pointer to the image data. width Specifies the width (in pixels) of the image. height Specifies the height (in pixels) of the image. bitmap_padSpecifies the quantum of a scanline. In other words, the start of one scanline is separated in client memory from the start of the next scanline by an integer multiple of this many bits. You must pass one of these values: 8, 16, or 32. bytes_per_lineSpecifies the number of bytes in the client image between the start of one scanline and the start of the next. If you pass a zero (0) value, Xlib assumes that the scanlines are contiguous in memory and calculates the value of bytes_per_line itself. The XCreateImage function allocates the memory needed for an XImage structure for the specified display. This function does not allocate space for the image itself. Rather, it initializes the structure with ``default'' values and returns a pointer to the XImage structure. The red, green, and blue mask values are defined for Z format images only December 18, 1987 - 332 - and are derived from the Visual structure passed in. The basic functions used to get a pixel, set a pixel, create a subimage, and add a constant offset to a Z format image are defined in the image object. The macros to call through the image object are defined in <X11/Xutil.h>. Use XGetPixel to obtain a pixel value in an image. The definition for this function is: unsigned long XGetPixel(ximage, x, y) XImage *ximage; int x; int y; ximage Specifies a pointer to the image. x y Specify the x and y coordinates. The XGetPixel function returns the specified pixel from the named image. The X and Y coordinates are relative to the origin (upper left [0,0]) of the image. The pixel value is returned in normalized format (that is, the least signifi- cant byte of the long is the least significant byte of the pixel). Use XPutPixel to set a pixel value in an image. The defini- tion for this function is: int XPutPixel(ximage, x, y, pixel) XImage *ximage; int x; int y; unsigned long pixel; ximage Specifies a pointer to the image. x y Specify the x and y coordinates. pixel Specifies the new pixel value. The XPutPixel function overwrites the pixel in the named image with the specified pixel value. The X and Y coordi- nates are relative to the origin (upper left [0,0]) of the image. The input pixel value must be in normalized format. That is, the least significant byte of the long is the least significant byte of the pixel. December 18, 1987 - 333 - Use XSubImage to create a subimage. The definition for this function is: XImage *XSubImage(ximage, x, y, subimage_width, subimage_height) XImage *ximage; int x; int y; int subimage_width; int subimage_height; ximage Specifies a pointer to the image. x y Specify the x and y coordinates. subimage_widthSpecifies the width (in pixels) of the new subimage. subimage_heightSpecifies the height (in pixel) of the new subimage. The XSubImage function creates a new image that is a subsec- tion of an existing one. It allocates the memory necessary for the new XImage structure and returns a pointer to the new image. The algorithm used is repetitive calls to XGet- Pixel and XPutPixel. Therefore, this function may be very slow. Use XAddPixel to increment each pixel in the pixmap by a constant value. The definition for this function is: int XAddPixel(ximage, value) XImage *ximage; int value; ximage Specifies a pointer to the image. value Specifies the constant value that is to be added. The XAddPixel function adds a constant value to every pixel in an image. This function is very useful when you have a base pixel value from allocating color resources and need to manipulate the image to that form. Use XDestroyImage to deallocate the memory allocated in a previous call to XCreateImage. The definition for this function is: int XDestroyImage(ximage) XImage *ximage; December 18, 1987 - 334 - ximage Specifies a pointer to the image. The XDestroyImage function deallocates the memory associated with the XImage 10.10. Manipulating Bitmaps Xlib provides functions with which you can read a bitmap from a file, save a bitmap to a file, or create a bitmap. This section describes those functions that transfer bitmaps to and from the client's file system, thus allowing their reuse in a later connection (for example, from an entirely different client or to a different display or server). Use XReadBitmapFile to read a bitmap in from disk. The definition for this function is: int XReadBitmapFile(display, d, filename, width_return, height_return, bitmap_return, x_hot_return, y_hot_return) Display *display; Drawable d; char *filename; int *width_return, *height_return; Pixmap *bitmap_return; int *x_hot_return, *y_hot_return; display Specifies the connection to the X server. d Specifies the drawable. filename Specifies the file name to use. The format of the file name is operating system specific. width_return height_returnReturns the width and height values of the read in bitmap file. bitmap_returnReturns the bitmap ID that is created. x_hot_return y_hot_returnReturns the hot spot coordinates. The XReadBitmapFile function reads in a file containing a bitmap. The file can be either in the standard X version 10 format (that is, the format used by X version 10 bitmap pro- gram) or in the newer X version 11 bitmap format. If the file cannot be opened, XReadBitmapFile returns BitmapOpen- Failed. If the file can be opened but does not contain valid bitmap data, XReadBitmapFile returns BitmapFileIn- valid. If insufficient working storage is allocated, XRead- BitmapFile returns BitmapNoMemory. If the file is readable and valid, XReadBitmapFile returns BitmapSuccess. December 18, 1987 - 335 - XReadBitmapFile assigns the bitmap's height and width, as read from the file, to the caller's variables width and height. It then creates a pixmap of the appropriate size, reads the bitmap data from the file into the pixmap and assigns the pixmap to the caller's variable bitmap. The caller must free the bitmap using XFreePixmap when done. If x_hot and y_hot are non-NULL, XReadBitmapFile sets *x_hot and *y_hot to the value of the hot spot as defined in the file. If no hot spot is defined, XReadBitmapFile sets *x_hot and *y_hot to -1,-1. Use XWriteBitmapFile to write out a bitmap to a file. The definition for this function is: int XWriteBitmapFile(display, filename, bitmap, width, height, x_hot, y_hot) Display *display; char *filename; Pixmap bitmap; int width, height; int x_hot, y_hot; display Specifies the connection to the X server. filename Specifies the file name to use. The format of the file name is operating system specific. bitmap Specifies the bitmap to be written. width height Specify the width and height. These are the dimensions of the bitmap to be written. x_hot y_hot Specifies where to place the hot spot coordinates (or -1,-1 if none are present) in the file. The XWriteBitmapFile function writes a bitmap out to a file. The file is written out in X version 11 bitmap format, which is the format used by the X version 11 bitmap program. Refer to that program's man pages for details. While XReadBitmap- File can read in either X version 10 format or X version 11 format, XWriteBitmapFile always writes out X version 11 for- mat only. If the file cannot be opened for writing, XWri- teBitmapFile returns BitmapOpenFailed. If insufficient memory is allocated XWriteBitmapFile returns BitmapNoMemory. Otherwise, on no error, XWriteBitmapFile returns BitmapSuc- cess. If x_hot and y_hot are not -1, -1, XWriteBitmapFile writes them out as the hot spot coordinates for the bitmap. Use XCreateBitmapFromData to include a bitmap written out by XWriteBitmapFile in a program directly, as opposed to December 18, 1987 - 336 - reading it in every time at run time. The definition for this function is: Pixmap XCreateBitmapFromData(display, d, data, width, height) Display *display; Drawable d; char *data; int width, height; display Specifies the connection to the X server. d Specifies the drawable. data Specifies the location of the bitmap data. width height Specify the width and height. These are the dimensions of the bitmap to create. The XCreateBitmapFromData function allows you to include in your C program (using #include) a bitmap file that was writ- ten out by XWriteBitmapFile (X version 11 format only) and, without reading in the bitmap file, The following is an example of getting a gray bitmap: #include "gray.bitmap" Pixmap XCreateBitmapFromData(display, window, gray_bits, gray_width, gray_height); If insufficient working storage was allocated, XCreateBit- mapFromData returns NULL. It is the user's responsibly to free the bitmap using XFreePixmap when done. Resource Manager 10.11. Using the Resource Manager Note Currently, for the first MIT release, the greatest user of the resource manager is the X Toolkit, which is running approximately a release cycle behind the Xlib and the server. The interfaces described in this section are believed accurate and final. However, for this release, the resource manager is packaged as a separate library, called ``Xrm''. The resource manager essentially is a database manager. Definitions for its use are contained in the <X11/Xresource.h> header file. Consider an X-based mail reading application called xmail. Further assume that it is designed in such a manner that it December 18, 1987 - 337 - uses a complex window hierarchy, all the way down to indivi- dual command buttons which are actually small subwindows. If each window is properly assigned a name and class, it becomes easy for the user to specify attributes of any por- tion of the application. At the top level, it might consist of a paned window. One pane of the paned window is a button box window of command buttons, named toc. One of these command buttons is used to include (fetch) new mail. This window has a name ``xmail.toc.buttons.include'' and a class ``application.panelwindow.buttonbox.commandButton''. Its name is the name of its parent, ``xmail.toc.buttons'', fol- lowed by its name ``include''. Its class is the class of its parent, ``Application.Panelwindow.Buttonbox'', followed by its particular class, ``CommandButton''. The fully quali- fied name of an attribute is its name appended to the window name, and its class is its class appended to the window class. This button needs the following resources: o Title string o Font o Foreground color o Background color o Foreground color for its active state o Background color for its active state Each of the resources that this button needs are considered to be attributes of the button and, as such, have a name and a class. For example, the foreground color for the button in its active state might be named ``activeForeground'' and its class would be ``Color.'' When a window requests a resource (for example, a color), it passes the complete name and class of the resource along with the desired representation type to a lookup routine. The representation type lets a window request different representations for the same resource. For example, a color might be requested as a color record, a pixel, a pixmap, or a name string. Rather than require the application to store every possible representation of a resource, Xlib provides a mechanism for converting between representations. The interface is implemented in two layers. The top layer allows applications to store resources by name, class, and representation type, as well as to retrieve them given a fully qualified name, class, and destination representation. December 18, 1987 - 338 - The resource manager automatically calls a conversion rou- tine, if necessary and possible, to convert the stored representation to the destination representation. This layer is built on top of a primitive manager that pro- vides the ability to store entries by name and class and a way of retrieving these values given a full name and class. This layer stores uninterpreted variable length values and has no knowledge of resource representations. The algorithm for determining which resource name or names match a given query is the heart of the database. The idea is that resources are stored with only partially specified name and classes. The unspecified portions of the name match any part of a more completely specified name or class. In particular, all queries fully specify the name and class of the resource needed. The lookup algorithm then searches the database for the name that most closely matches this full name and class. The definition of a match is as follows: For a query of name N = n1.n2.n3...nk and class C = c1.c2.c3...ck, a partial name P = p1.p2.p3...pm matches (N,C), if P matches the regular expression [n1|c1] [n2|c2] [n3|c3]...[nk|ck]. The regular expression ``a|b'' matches either ``a'' or ``b'', ``[a]'' matches ``a'' or NULL (that is, ``a'' is optional), and ``a b'' matches ``a'' followed by ``b''. As they are defined, the name and the class have exactly the same number of components. If two distinct partial names P and Q both match (N,C), then the rule for establishing precedence is defined below. For P, construct a k element list (X = x1, x2, x3...xk). If ni is an element of P, then xi = 2. If ci is an element of P, then xi = 1. If any other case occurs, xi = 0. Construct a similar k element list for Q (Y = y1, y2, y3...yk). Compare X and Y by comparing the values of x1 and y1. If they are equal, compare x2 and y2, and so on. If X > Y, then the partial name P takes precedence over the par- tial name Q. For example, assume the following user preference specifica- tion: xmail.background: red button.font: Helv10 button.background: blue button.color: green xmail.toc.button.activeForeground:black xmail.toc.buttons.border:3 A query for the name ``xmail.toc.button.include.activeForeground'' and class December 18, 1987 - 339 - ``application.panelwindow.buttonbox.button.color'' matches ``xmail.toc.button.activeForeground'' and returns ``black''. However, it also matches ``button.color''. Using the precedence algorithm described above indicates that the ``xmail.toc.button.activeForeground'' specification is the one that ``wins''. Database values consist of a size and an address. The size is specified in machine dependent units, while the address is a machine-dependent pointer to uninterpreted machine memory, for example: typedef void (*XrmTypeConverter)(); The type conversion machinery calls conversion procedures to convert between differing resource representations. There are some predefined conversions, but clients can register as many new conversions as are needed. These registered conver- sion procedures have a type of XrmTypeConverter. They take a source type and value. Then, they convert them to a destina- tion type and value. There is a string (atom) for each defined resource representation type, and the values are size and address pairs. See XrmRegisterTypeConverter and XrmConvert for further information. A resource database is an opaque structure used by the lookup routines. typedef struct ResourceDataBaseStruct *ResourceDataBase; See XrmGetDataBase, XrmPutDataBase, and XrmMergeDataBases for further information. Xlib provides resource management functions with which you can manipulate the resource manager. The following sections discuss how to: o Store and get resources o Getting database levels o Convert resource values o Merge the resource database o Retrieve and store databases 10.11.1. Storing and Getting Resources Use XrmPutResource to store a resource in the database. The definition for this function is: December 18, 1987 - 340 - void XrmPutResource(db, list, data_type, value_descriptor) XrmResourceDataBase *db; XrmQuarkList list; XrmRepresentation data_type; XrmValuePtr value_descriptor; db Specifies the descriptor of the resource database. list Specifies the partial name or class list of the resource to be stored. data_type Specifies the data representation of the resource to be stored. value_descriptorSpecifies the descriptor for the resource entry. The XrmPutResource function takes a partial name, a representation type, and a value. The value is copied into the specified database db. Use XrmGetResource to retrieve a resource from the database. The definition for this function is: void XrmGetResource(screen, db, inher_name, inher_class, type, value_return) Screen screen; XrmResourceDataBase *db; XrmNameList inher_name; XrmClassList inher_class; XrmRepresentation type; XrmValuePtr *value_return; screen Specifies the screen that is to be used for the lookup. db Specifies the descriptor of the resource database. inher_nameSpecifies the full inheritance name of the value being retrieved. inher_classSpecifies the full inheritance class of the value being retrieved. type Specifies the representation type of the destina- tion. value_returnReturns the value, which represents a database address. The XrmGetResource function retrieves a resource from the database. It takes a full name/class pair, a destination December 18, 1987 - 341 - resource representation, and the address of a value (size/address pair). The value returned points into data- base memory. The value returned points into database memory. Therefore, the client should copy it to be safe. Currently, the database only frees or overwrites entries on XrmPutResource or XrmMergeDataBases. A client that is not doing any XrmPutResources or that is not merging the data- base should be safe using the address passed back. 10.11.2. Getting Database Levels Some applications and toolkits do not make random probes into the database to fetch resources. The toolkit access pattern for the database is quite stylized: a series of from one to twenty probes are made with only the last name/class differing in each probe. The XrmGetResource is at worst a 2^n algorithm (n is the length of the name/class list). Use XrmGetSearchList to return a list of database levels. The definition for this function is: void XrmGetSearchList(names, classes, list) XrmNameList names; XrmClassList classes; XrmSearchList ist; names Specifies a list of resource names. classes Specifies a list of resource classes. list Specifies an argument to which the list of data- base levels is returned. The XrmGetSearchList function takes a list of names and classes and returns a list of database levels where a match might occur. The returned list is a best-to-worst order and uses the same algorithm as XrmGetResource for determining precedence. Use XrmGetSearchResource to search the database levels for a given resource. The definition for this function is: XGetSearchResource(screen, list, name, class, type, value) Screen *screen; XrmSearchList list; XrmName name; XrmClass class; XrmAtom type; XrmValuePtr value; December 18, 1987 - 342 - screen Specifies the screen. list Specifies the list of database levels that are to be searched. name Specifies the resource name. class Specifies the resource class. type Specifies data representation type. values Specifies a pointer to which the matched resource is returned. The XrmGetSearchResource function searches the specified database levels for the resource that is fully identified by the specified name and class. If it finds the resource, XrmGetSearchResource first converts it to the specified type and then returns this converted resource to the value argu- ment. The search stops with the first match. If it does not find the resource, XrmGetSearchResource returns NULL. 10.11.3. Converting Resource Values Use XrmConvert to convert a value from one representation to another. For example, a client might want to convert the string ``blue'' to a pixel that will appear blue on a given screen. The predefined types can be found in <X11/Xresource.h>. The definition for this function is: void XrmConvert(screen, from_type_convert, from, to_type_convert, to) Screen screen; XrmAtom from_type_convert; XrmValuePtr from; XrmAtom to_type_convert; XrmValuePtr to; screen Specifies the screen that is to be used for the conversion. from_type_convertSpecifies the string (atom) describing the type to be converted. from Specifies the typed value descriptor for the type to be converted. to_type_convertSpecifies the string (atom) describing the type desired. to Specifies the descriptor that is to receive the converted value. December 18, 1987 - 343 - Use XrmRegisterTypeConverter to extend the resource manager conversion mechanism. The definition for this function is: void XrmRegisterTypeConverter(from_type, to_type, proc) XrmAtom from_type, to_type; XrmTypeConverter proc; from_type Specifies the source value type. to_type Specifies the destination value type. proc Specifies the conversion procedure used to convert the value. The XrmRegisterTypeConverter function allows clients to extend the mechanism by which the resource manager converts between representations. This is especially useful for those clients who wish to extend the known representation types. If there is no conversion from the source type to the destination type, then NULLs are returned for the desti- nation size and address. This procedure is used by the higher-level resource manager to implement XrmGetResource. The converters themselves have the following calling sequence: void yourTypeConverter(screen, from_value, to_value_return) Screen *screen; XrmValuePtr from_value; XrmValuePtr to_value_return; screen Specifies that the conversion is performed rela- tive to the specified screen. from_valueSpecifies the value to be converted. to_value_returnReturns the value after the conversion. Your conversion routine should convert the from_value to the target type. 10.11.4. Merging Resource Databases Use XrmMergeDataBases to merge the contents of one database into another. The definition for this function is: void XrmMergeDataBases(new, into) XrmResourceDataBase new, *into; December 18, 1987 - 344 - new Specifies the descriptor of the resource database to be merged into the existing database. into Specifies the descriptor of the resource database into which the new database will be merged. The XrmMergeDataBases function may overwrite entries in the destination database. This procedure is used to combine databases (for example, an application specific database of defaults and a database of user preferences). 10.11.5. Retrieving and Storing Databases Use XrmGetDataBase to retrieve a database from nonvolatile storage. The definition for this function is: XrmResourceDataBase XrmGetDataBase(db_filename) char *db_filename; db_filenameSpecifies the resource database file name. The XrmGetDataBase function is used primarily to get a copy of the global user-preference database. However, it also can be used to retrieve stored copies of other resource databases (perhaps, those from earlier invocations of the program or a database editor). Use XrmPutDataBase to store a copy of the application's current database in nonvolatile storage. The definition for this function is: void XrmPutDataBase(db_filename, db) char *db_filename; XrmResourceDataBase db; db_filenameSpecifies the resource database file name. db Specifies the descriptor of the resource database. The XrmPutDataBase function stores a copy of the application's current database into a file. Use XrmLoadDataBase to retrieve a resource from the database and add it to a string. The definition for this function is: XrmResourceDataBase XrmLoadDataBase(data) char *data; December 18, 1987 - 345 - data Specifies the data string. The XrmLoadDataBase adds the resources in the specified null-terminated string. XrmLoadDataBase is similar to XrmGetDataBase, except that it reads the information out of a string instead of a file. 10.11.6. Parsing Command Line Options Use XrmParseCommand to load a resource data base from a C command line. The definition for this function is: typedef enum { XrmoptionNoArg, /* Value is specified in OptionDescRec.value */ XrmoptionIsArg, /* Value is the option string itself */ XrmoptionStickyArg, /* Value is characters immediately following option */ XrmoptionSepArg, /* Value is next argument in argv */ XrmoptionSkipArg, /* Ignore this option and the next argument in argv */ XrmoptionSkipLine /* Ignore this option and the rest of argv */ } XrmOptionKind; typedef struct { char *option; /* Option abbreviation in argv */ char *resourceName; /* Resource name (sans application name) */ XrmOptionKind argKind;/* Which style of option it is */ caddr_t value; /* Value to provide if XrmoptionNoArg */ } XrmOptionDescRec, *XrmOptionDescList; void XrmParseCommand(db, table, table_count, name, argc_return, argv_return,) XrmResourceDataBase *db; XrmOptionDescList table; int table_count; char *name; int *argc_return; char **argv_return; db Specifies the descriptor of the resource database. table Specifies table of command line arguments to be parsed. count Specifies the number of entries in the table. name Specifies the application name. argc_returnBefore the call, contains the number of argu- ments, after the call, returns the number of remaining arguments. December 18, 1987 - 346 - argv_returnBefore the call, a pointer to the command line arguments. After the call, matched arguments have been removed. The XrmParseCommand function parses an (arc, argv) pair in your main program according to the specified option table, loads recognised options into the specified database, and modifies the (arc, argv) pair to remove all recognised options. The specified table is used to parse the command line. Recognised entries in the table are removed from argv, and entries are made in the specified resource data base. The table entries contain information on the option string, the the option name, which style of option and a value to pro- vide if the option kind is XrmoptionNoArg. The argc argu- ment specifies the number of arguments in argv, and is set to the remaining number of arguments that were not parsed. The name argument should be the name of your application for use in building the data base entry. 10.12. Using the Context Manager The context manager provides a way of associating data with a window in your program. Any amount of data in any number of pieces can be associated with a window, and each piece of data has a type associated with it. The context manager requires knowledge of the window ID and type to store or retrieve data. Essentially, the context manager can be viewed as a two- dimensional, sparse array: one dimension is subscripted by the window ID and the other by a context type field. Each entry in the array contains a pointer to the data. Xlib provides context management functions with which you can save data values, get data values, delete entries, and create a unique context type. The symbols used are in <X11/Xutil.h> header file. Use XSaveContext to save a data value that corresponds to a window and context type. The definition for this function is: int XSaveContext(display, w, context, data) Display *display; Window w; XContext context; caddr_t data; December 18, 1987 - 347 - display Specifies the connection to the X server. w Specifies the window with which the data is asso- ciated. context Specifies the context type to which the data belongs. data Specifies the data to be associated with the win- dow and type. If an entry with the specified window and type already exists, XSaveContext overrides it with the specified con- text. However, this override has costs in time and space. If you know the entry already exists, it is better to call XDeleteContext first. The XSaveContext function returns nonzero error code if an error has occurred and zero (0) otherwise. Possible errors are XCNOMEM (out of memory). Use XFindContext to get the data associated with a window and type. The definition for this function is: int XFindContext(display, w, context, data_return) Display *display; Window w; XContext context; caddr_t *data_return; display Specifies the connection to the X server. w Specifies the window with which the data is asso- ciated. context Specifies the context type to which the data belongs. data_returnReturns a pointer to the data. Because it is a return value, the data is a pointer. The XFindContext function returns nonzero error code if an error has occurred and zero (0) otherwise. Possible errors are XCNOENT (context-not-found). Use XDeleteContext to delete an entry for a given window and type. The definition for this function is: int XDeleteContext(display, w, context) Display *display; Window w; XContext context; December 18, 1987 - 348 - display Specifies the connection to the X server. w Specifies the window with which the data is asso- ciated. context Specifies the context type to which the data belongs. The XDeleteContext function deletes the entry for the given window and type from the data structure. This returns the same error codes that XFindContext returns if called with the same arguments. Use XUniqueContext to create a unique context type that may be used in subsequent calls to XSaveContext. and XFindCon- text. The definition for this function is: XContext XUniqueContext() December 18, 1987 - 349 - Appendix A Protocol Extensions Appendix A - Protocol Extensions Because X can only evolve by extension to the core protocol, it is important that extensions not be perceivable as second class citizens. At some point, your favorite extensions may be adopted as addi- tional parts of the ``X Standard''. Therefore, there should be little to distinguish the use of an extension from that of the core protocol. To avoid hav- ing to initialize extensions explicitly in application pro- grams, it is also important that extensions perform ``lazy evaluations'' and automatically initialize themselves when called for the first time. This appendix describes techniques for writing extensions to Xlib that will run at essentially the same performance as the core protocol requests. Note It is expected that a given extension to X con- sists of multiple requests. Defining 10 new features as 10 separate extensions is very bad practice. Rather, they should be packaged into a single extension and should use minor opcodes to distinguish the features. Basic Protocol Support Routines The basic protocol requests for extensions are XQueryExten- sion, XListExtensions. Bool XQueryExtension(display, name, major_opcode, first_event, first_error) Display *display; char *name; int *major_opcode; /* RETURN */ int *first_event; /* RETURN */ int *first_error; /* RETURN */ XQueryExtension determines if the named extension is present. If so, the major opcode for the extension is returned (if it has one). Otherwise, zero is returned. Any minor opcode and the request formats are specific to the extension. If the extension involves additional event types, the base event type code is returned. Otherwise, zero is returned. The format of the events is specific to the December 18, 1987 - 350 - extension. If the extension involves additional error codes, the base error code is returned. Otherwise, zero is returned. The format of additional data in the errors is specific to the extension. The extension name should be in the ISO LATIN-1 encoding, and upper/lower case does matter. char **XListExtensions(display, nextensions) Display *display; int *nextensions; XListExtensions returns a list of all extensions supported by the server. XFreeExtensionList(list) char **list; XFreeExtensionList frees the memory allocated by XListExten- sions. Hooking into Xlib These functions allow one to hook into the library. They are not normally used by application programmers but are used by people who need to extend the core X protocol and the X library interface. The functions, which generate protocol requests for X, are typically called ``stubs''. In extensions, stubs first should check to see if they have initialized themselves on a connection. If they have not, they then should call XInitExtension to attempt to initial- ize themselves on the connection. If the extension needs to be informed of GC/font allocation or deallocation, or if the extension defines new event types, the functions described in the following sections allow an extension to be called when these events occur. In <X11/Xlib.h>, the following structure is defined to return the information from XQueryExtension. typedef struct _XExtCodes { /* public to extension, cannot be changed */ int extension; /* extension number */ int major_opcode; /* major op-code assigned by server */ int first_event; /* first event number for the extension */ int first_error; /* first error number for the extension */ } XExtCodes; XExtCodes *XInitExtension(display, name) Display *display; char *name; December 18, 1987 - 351 - XInitExtension first calls XQueryExtension to see if the extension exists. Then, it allocates storage for maintaining the information about the extension on the connection, chains this onto the extension list for the connection, and returns the information the stub implementor will need to access the extension. In particular, the extension number in the XExtCodes struc- ture is needed in other calls below. This extension number is unique only to a single connection. Hooks into the Library These functions allow you to define procedures which are to be called when various circumstances occur. The procedures include the creation of a new GC for a connection, the copy- ing of a GC, the freeing a GC, the creating and freeing of fonts, the conversion of events defined by extensions to and from wire format, and the handling of errors. All of these functions return the previous routine defined for this extension. int (*XESetCloseDisplay(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when display closed */ You use this procedure to define a procedure to be called whenever XCloseDisplay is called. This procedure returns any previously defined procedure, usually NULL. When XCloseDisplay is called, your routine is called with these arguments: (*proc)(display, codes) Display *display; XExtCodes *codes; int (*XESetCreateGC(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when GC created */ You use this procedure to define a procedure to be called whenever a new GC is created. This procedure returns any previously defined procedure, usually NULL. When a GC is created, your routine will be called with these arguments: December 18, 1987 - 352 - (*proc)(display, gc, codes) Display *display; GC gc; XExtCodes *codes; int (*XESetCopyGC(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when GC copied */ You use this procedure to define a procedure to be called whenever a GC is copied. This procedure returns any previ- ously defined procedure, usually NULL. When a GC is copied, your routine will be called with these arguments: (*proc)(display, gc, codes) Display *display; GC gc; XExtCodes *codes; int (*XESetFreeGC(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when GC freed */ You use this procedure to define a procedure to be called whenever a GC is freed. This procedure returns any previ- ously defined procedure, usually NULL. When a GC is freed, your routine will be called with these arguments: (*proc)(display, gc, codes) Display *display; GC gc; XExtCodes *codes; int (*XESetCreateFont(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when font created */ You use this procedure to define a procedure to be called whenever XLoadQueryFont is called. This procedure returns any previously defined procedure, usually NULL. December 18, 1987 - 353 - When XLoadQueryFont is called, your routine will be called with these arguments: (*proc)(display, fs, codes) Display *display; XFontStruct *fs; XExtCodes *codes; int (*XESetFreeFont(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when font freed */ You use this procedure to define a procedure to be called whenever XFreeFont is called. This procedure returns any previously defined procedure, usually NULL. When XFreeFont is called, your routine will be called with these arguments: (*proc)(display, fs, codes) Display *display; XFontStruct *fs; XExtCodes *codes; The next two functions allow you to define new events to the library. Note There is an implementation limit such that your host event structure size cannot be bigger than the size of the XEvent union of structures. int (*XESetWireToEvent(display, event_number, proc))() Display *display; /* display */ int event_number; /* event routine to replace */ int (*proc)(); /* routine to call when converting event */ You use this procedure to define a procedure to be called when an event needs to be converted from wire format ( xEvent) to host format ( XEvent) form. The event number defines which protocol event number to install a conversion routine for. This procedure returns any previously defined procedure. Note You can replace a core event conversion routine with one of your own, though this is not encouraged. It would, however, allow you to December 18, 1987 - 354 - intercept a core event and modify it before being enqueued or otherwise examined. When Xlib needs to convert an event from wire format to natural host format, your routine will be called with these arguments: (*proc)(display, re, event) Display *display; XEvent *re; xEvent event; The re argument is a pointer to where the host format event should be stored, while the event argument is the 32-byte wire event structure. In the XEvent structure you are creating, type must be the first member and window must be the second member. You should fill in the type member with the type specified for the xEvent structure. You should copy all other members from the xEvent structure (wire for- mat) to the XEvent structure (host format). int (*XESetEventToWire(display, event_number, proc))() Display *display; /* display */ int event_number; /* event routine to replace */ (*proc)(); /* routine to call when converting event */ You use this procedure to define a procedure to be called when an event needs to be converted from host format ( XEvent) to wire format ( xEvent) form. The event number defines which protocol event number to install a conversion routine for. This procedure returns any previously defined procedure. Note You can replace a core event conversion routine with one of your own, though this is not encouraged. It would, however, allow you to inter- cept a core event and modify it before being sent to another client. When Xlib needs to convert an event from wire format to natural host format, your routine will be called with these arguments: (*proc)(display, re, event) Display *display; XEvent *re; xEvent event; The re argument is a pointer to the host format event, while the event argument is a pointer to where the 32-byte wire event structure should be stored. In the XEvent structure that you are forming, you must have ``type'' the first December 18, 1987 - 355 - element and ``window'' the second. You then should fill in the type with the type from the xEvent structure. All other elements then should be copied from the wire format to the XEvent structure. int (*XESetError(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ int (*proc)(); /* routine to call when X error happens */ Inside Xlib, there are times that you may want to suppress the calling of the external error handling when an error occurs. This allows status to be returned on a call at the cost of the call being synchronous (though most such rou- tines are query operations, in any case, and are typically programmed to be synchronous). When Xlib detects an protocol error in _XReply, it will call your procedure with these arguments: int (*proc)(display, err, codes, ret_code) Display *display; xError *err; XExtCodes *codes; int *ret_code; The err argument is a pointer to the 32 byte wire format error. The codes argument is a pointer to the extension codes structure. The ret_code argument is the return code you may want _XReply to return. If your routine returns a value 0, the error is not suppressed, and XError is called. If your routine returns nonzero, the error is suppressed, and _XReply returns the value of ret_code. char *(*XESetErrorString(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ char *(*proc)(); /* routine to call when I/O error happens */ int (*XESetFlushGC(display, extension, proc))() Display *display; /* display */ int extension; /* extension number */ char *(*proc)(); /* routine to call when I/O error happens */ The XESetFlushGC procedure is identical to XSetCopyGC, except that XESetFlushGC is called when a GC is cache need to be updated in the server. The XGetErrorText function returns a string to the user for an error. This procedure allows you to define a routine to be called which should return a pointer to the error December 18, 1987 - 356 - message. The following is an example. char *(*proc)(display, code, codes) Display *display; int code; XExtCodes *codes; Your procedure is called with the error code detected. You should return a pointer to a null terminated string contain- ing the error message. Hooks onto Xlib Data Structures Various Xlib data structures have provisions for extension routines to chain extension supplied data onto a list. These structures are: GC, Visual, Screen, ScreenFormat, Display, and XFontStruct. Because the list pointer is always the first element in the structure, a single set of routines can be used to manipulate the data on these lists. The following structure is used in the routines in this sec- tion and is defined in <X11/Xlib.h>. typedef struct _XExtData { int number; /* number returned by XInitExtension */ struct _XExtData *next; /* next item on list of data for structure */ int (*free)(); /* if defined, called to free private */ char *private; /* data private to this extension. */ } XExtData; When any of the data structures listed above are freed, the list is walked, and the free routine (if any) is called. If free is NULL, then the library will free the data pointed to by private and the structure, itself. XAddToExtensionList(structure, ext_data) struct _XExtData **structure;/* pointer to structure to add */ XExtData *ext_data; /* extension data structure to add */ The structure argument is a pointer to one of the data structures enumerated above. You must initialize ext_data- >number with the extension number before calling this rou- tine. It is expected that an extension will add at most one exten- sion data structure to any single data structure's extension data list. XExtData *XFindOnExtensionList(structure, number) struct _XExtData **structure; int number; /* extension number from XInitExtension*/ XFindOnExtensionList returns the first extension data struc- ture for the extension numbered number. December 18, 1987 - 357 - The XAllocID macro, which allocates and returns a resource ID, is defined in <X11/Xlib.h>. XAllocIDdisplay) Display *display; This macro is a call through the Display structure to the internal resource ID allocator. It returns a resource ID that you can use when creating new resources. GC Caching GCs are cached by the library, to allow merging of indepen- dent change requests to the same GC into single protocol requests. This is typically called a "write back" cache. Any extension routine whose behavior depends on the contents of a GC must flush the GC cache, to make sure the server has up to date contents in its GC. The FlushGC macro checks the dirty bits in the library's GC structure and calls _XFlushGCCache if any elements have changed. The FlushGC macros is defined as follows: FlushGC (display, gc) Display *display; GC gc; Note that if you extend the GC to add additional resource ID components, you should ensure that the library stub immedi- ately sends the change request. This is because a client can free a resource immediately after using it, so if you only stored the value in the cache without forcing a proto- col request, the resource might be destroyed before being set into the GC. You can use the _XFlushGCCache procedure to force the cache to be flushed. The _XFlushGCCache pro- cedure is defined as follows: _XFlushGCCache (display, gc) Display *display; GC gc; Graphics Batching If you extend X to add more poly graphics primitives, you may be able to take advantage of facilities in the library to allow back-to-back single calls to be transformed into poly requests. This may dramatically improve performance of programs that are not written using poly requests. In the display structure is a pointer to an xReq called last_req which is the last request being processed. By checking that the last request type, drawable, gc, and other options are the same as the new one, and that there is enough space left December 18, 1987 - 358 - in the buffer, you may be able to just extend the previous graphics request by extending the length field of the request and appending the data to the buffer. This can cause a 5 times or more improvement in stupid programs. For exam- ple, here is the source for the XDrawPoint stub. (Writing extension stubs is discussed in the next section.) #include "copyright.h" #include "Xlibint.h" /* precompute the maximum size of batching request allowed */ static int size = sizeof(xPolyPointReq) + EPERBATCH * sizeof(xPoint); XDrawPoint(dpy, d, gc, x, y) register Display *dpy; Drawable d; GC gc; int x, y; /* INT16 */ { xPoint *point; LockDisplay(dpy); FlushGC(dpy, gc); { register xPolyPointReq *req = (xPolyPointReq *) dpy->last_req; /* if same as previous request, with same drawable, batch requests */ if ( (req->reqType == X_PolyPoint) && (req->drawable == d) && (req->gc == gc->gid) && (req->coordMode == CoordModeOrigin) && ((dpy->bufptr + sizeof (xPoint)) <= dpy->bufmax) && (((char *)dpy->bufptr - (char *)req) < size) ) { point = (xPoint *) dpy->bufptr; req->length += sizeof (xPoint) >> 2; dpy->bufptr += sizeof (xPoint); } else { GetReqExtra(PolyPoint, 4, req); /* 1 point = 4 bytes */ req->drawable = d; req->gc = gc->gid; req->coordMode = CoordModeOrigin; point = (xPoint *) (req + 1); } point->x = x; point->y = y; } UnlockDisplay(dpy); SyncHandle(); } There is a limit of EPERBATCH on the number of requests December 18, 1987 - 359 - batched, to keep clients from generating very long requests that may monopolize the server. Most of the performance benefit occurs in the first few merged requests. Note that FlushGC is called BEFORE picking up the value of last_req, since it may modify this field. Writing Extension Stubs All X requests always contain the length of the request, expressed as a 16-bit quantity of 32-bits. This means that a single request can be no more than 256k Bytes in length. Some servers may not support single requests of such a length. The value of dpy->max_request_size contains the maximum length as defined by the server implementation. For further information, see the X Protocol documentation. Requests, Replies, and Xproto.h It may make it easier to understand if you look at the Xproto.h header file. The file contains three sets of defin- itions that are of interest to the stub implementor: request names, request structures, and reply structures. You need to generate a file equivalent to Xproto.h for your extension and need to include it in your stub routine. Each stub routine also must include Xlibint.h. The identifiers are deliberately chosen in such a way that, if the request is called X_DoSomething, then its request structure is xDoSomethingReq, and its reply is xDo- SomethingReply. The ``GetReq'' family of macros, defined in Xlibint.h, takes advantage of this naming scheme. For each X Request, there is a definition in Xproto.h that looks similar to this: #define X_DoSomething 42 In your extension header file, this will be a minor op-code, instead of a major opcode. Request Format Every request contains an 8-bit ``major'' opcode and a 16- bit length field expressed in units of 4 bytes. Every request consists of 4 bytes of header (containing the major opcode, the length field, and a data byte) followed by zero or more additional bytes of data. The length field defines the total length of the request, including the header. The length field in a request must equal the minimum length required to contain the request. If the specified length is smaller or larger than the required length, the extension should generate a BadLength error. Unused bytes in a December 18, 1987 - 360 - request are not required to be zero. Major opcodes 128 through 255 are reserved for extensions. Extensions are intended to contain multiple requests, so extension requests typically have an additional minor opcode encoded in the ``spare'' data byte in the request header, but the placement and interpretation of this minor opcode as well as all other fields in extension requests are not defined by the core protocol. Every request is implicitly assigned a sequence number (starting with one) used in replies, errors, and events. Most protocol requests have a corresponding structure typedef in Xproto.h, which looks like: typedef struct _DoSomethingReq { CARD8 reqType; /* X_DoSomething */ CARD8 someDatum; /* used differently in different requests */ CARD16 length; /* total # of bytes in request, divided by 4 */ ... /* request-specific data */ ... } xDoSomethingReq; If a core protocol request has a single 32-bit argument, you need not declare a request structure in your extension header file. Instead, such requests use Xproto.h's xResour- ceReq structure. This structure is used for any request whose single argument is a Window, Pixmap, Drawable, GCon- text, Font, Cursor, Colormap, Device, Atom, VisualID, or Time. typedef struct _ResourceReq { CARD8 reqType; /* the request type, e.g. X_DoSomething */ BYTE pad; /* not used */ CARD16 length; /* 2 (= total # of bytes in request, divided by 4) */ CARD32 id; /* the Window, Drawable, Font, GContext, etc. */ } xResourceReq; If convenient, you can do something similar in your exten- sion header file. In both of these structures, the reqType field identifies the type of the request (for example, X_MapWindow or X_CreatePixmap). The length field tells how long, in units of 4-byte ``longwords'', the request is. This length includes both the request structure itself and any variable length data, such as strings or lists, that follow the request structure. Request structures come in different sizes, but all requests are padded to be a multiple of 4 bytes long. A few protocol requests take no arguments at all. Instead, they use Xproto.h's xReq structure, which contains only a December 18, 1987 - 361 - reqType and a length (and a pad byte). If the protocol request requires a reply, then Xproto.h also contains a reply structure typedef: typedef struct _DoSomethingReply { BYTE type; /* always X_Reply */ BYTE someDatum; /* used differently in different requests */ CARD16 sequenceNumber; /* # of requests sent so far */ CARD32 length; /* # of additional bytes, divided by 4 */ ... /* request-specific data */ ... } xDoSomethingReply; Most of these reply structures are 32 bytes long. If there are not that many reply values, then they contain a suffi- cient number of pad fields to bring them up to 32 bytes. The length field is the total number of bytes in the request minus 32, divided by 4. This length will be nonzero only if: o The reply structure is followed by variable length data such as a list or string o The reply structure is longer than 32 bytes Only GetWindowAttributes, QueryFont, QueryKeymap, and Get- KeyboardControl have reply structures longer than 32 bytes. A few protocol requests return replies that contain no data. Xproto.h does not define reply structures for these. Instead, they use the xGenericReply structure, which con- tains only a type, length, and sequence number (and suffi- cient padding to make it 32 bytes long). Starting to Write a Stub Routine An Xlib stub routine should always start like this: #include "Xlibint.h" XDoSomething (arguments, ... ) /* argument declarations */ { /* variable declarations, if any */ If the protocol request has a reply, then the variable declarations should include the reply structure for the request. The following is an example. xDoSomethingReply rep; December 18, 1987 - 362 - Locking Data Structures Note Locking has not yet been tested as of September 2, 1987! In order to lock the display structure, for systems which want to support multithreaded access to a single display connection, each stub will need to lock its critical sec- tion. Generally, this section is the point from just before the appropriate GetReq call documented below and when all arguments to the call have been stored into the request. The precise instructions needed for this locking depend upon the machine architecture. Two calls, which are generally implemented as macros, have been provided. LockDisplay(display) Display *display; UnlockDisplay(display) Display *display; Sending the Protocol Request and Arguments After the variable declarations, a stub routine should call one of four macros defined in Xlibint.h: GetReq, GetReqEx- tra, GetResReq, or GetEmptyReq. All of these macros take as their first argument the name of the protocol request as declared in Xproto.h, except with "X_" removed. Each one declares a Display structure pointer, called ``dpy'', and a pointer to a request structure, called ``req'', which is of the appropriate type. The macro then appends the request structure to the output buffer, fills in its type and length field, and sets "req" to point to it. If the protocol request has no arguments (for instance, X_GrabServer), then use GetEmptyReq: GetEmptyReq (DoSomething); If the protocol request has a single 32-bit argument (such as, a Pixmap, Window, Drawable, Atom, and so on), then use GetResReq. The second argument to the macro is the 32-bit object. X_MapWindow is a good example. GetResReq (DoSomething, rid); The rid argument is the Pixmap, Window, or other resource December 18, 1987 - 363 - ID. If the protocol request takes any other argument list, then call GetReq. After the GetReq, you need to set all the other fields in the request structure, usually from argu- ments to the stub routine. GetReq (DoSomething); /* fill in arguments here */ req->arg1 = arg1; req->arg2 = arg2; A few stub routines (such as, XCreateGC and XCreatePixmap) return a resource ID to the caller but pass a resource ID as an argument to the protocol request. Such routines use the macro XAllocID to allocate a resource ID from the range of IDs that were assigned to this client when it opened the connection. rid = req->rid = XAllocID(); return (rid); Finally, some stub routines transmit a fixed amount of variable-length data after the request. Typically, these are routines (such as, XMoveWindow and XSetBackgroundPixel) are special cases of more general functions like XMoveResizeWin- dow and XChangeGC. These special case routines use GetReqExtra, which is the same as GetReq, except that it takes an additional argument (the number of extra bytes to allocate in the output buffer after the request structure). This number should always be a multiple of 4. Variable Length Arguments Some protocol requests take additional variable length data that follow the xDoSomethingReq structure. The format of these data varies from request to request. Some require a sequence of 8-bit bytes, others a sequence of 16- or 32-bit entities, and still others a sequence of structures. It is necessary to add the length of any variable length data to the length field of the request structure. That length field is in units of 32-bit longwords. If the data is a string or other sequence of 8-bit bytes, then you must round the length up and shift it before adding: req->length += (nbytes+3)>>2; To transmit the variable length data, use the Data macro. If the data fits into the output buffer, then this macro copies it to the buffer. If it does not fit, however, the Data December 18, 1987 - 364 - macro calls _XSend, which transmits first the contents of the buffer and then your data. The Data macro takes three arguments: the Display, a pointer to the beginning of the data, and the number of bytes to be sent. Data(dpy, (char *) data, nbytes); If the data are 16-bit entities, then use the PackData macro instead. It takes the same arguments and does the same things, but it does the right thing on machines where a short is 32-bits instead of the usual 16. Both Data and PackData are macros which may use their last argument more than once, so that argument should be a vari- able rather than an expression such as ``nitems*sizeof(item)''. You should do that kind of computa- tion in a separate statement before calling Data. If the protocol request requires a reply, then call the pro- cedure _XSend instead of the Data macro. _XSend takes the same arguments, but, because it sends your data immediately instead of copying it into the output buffer (which would later be flushed anyway by the following call on _XReply), it is faster. Replies If the protocol request has a reply, then call _XReply after you have finished dealing with all the fixed and variable length arguments. _XReply flushes the output buffer and waits for an xReply packet to arrive. If any events arrive in the meantime, _XReply enqueues them for later use. Status _XReply(display, rep, extra, discard) Display *display; xReply *rep; int extra; /* number of 32-bit words expected after the reply */ Bool discard; /* should I discard data following "extra" words? */ _XReply waits for a reply packet and copies its contents into the specified rep. _XReply handles error and event packets that occur before the reply is received. _XReply takes four arguments: o A Display * structure o A pointer to an reply structure (which must be cast to an xReply *) o The number of additional bytes (beyond sizeof(xReply) = 32 bytes) in the reply structure o A boolean which tells _XReply to discard any additional bytes beyond those it was told to read December 18, 1987 - 365 - Because most reply structures are 32 bytes long, the third argument is usually 0. The only exceptions are the replies to GetWindowAttributes, QueryFont, QueryKeymap, and GetKey- boardControl in the core protocol, which have longer replies. The last argument should be xFalse, if the reply structure is followed by additional variable length data (such as, a list or string). It should be xTrue if there is not any variable length data. Note This last argument is provided for upward- compatibility reasons--to allow a client to com- municate properly with a hypothetical later ver- sion of the server which sends more data than the client expected. For example, some later version of GetWindowAttributes might use a larger, but compatible, xGetWindowAttributesReply which con- tains additional attribute data at the end. _XReply returns true, if it received a reply successfully, or false, if it received an XError instead (or some other error condition occurred). For a request with a reply that is not followed by variable length data, you write something like: _XReply (display, (xReply *)&rep, 0, xTrue); *ret1 = rep.ret1; *ret2 = rep.ret2; *ret3 = rep.ret3; UnlockDisplay(dpy); SyncHandle(); return (rep.ret4); } If there is variable length data after the reply, change the ``xTrue'' to ``xFalse'', and use _XRead to read the variable-length data. Each protocol request is a little different. For further information, see the Xlib sources for examples. Synchronous Calling To ease debugging, each routine should have a call to a rou- tine, just before returning to the user, called SyncHan- dle(). This routine generally is implemented as a macro. If synchronous mode is enabled (see XSynchronize), the request is sent immediately. The library, however, waits until any error the routine could generate at the server has December 18, 1987 - 366 - been handled. Allocating and Deallocating Memory To support the possible reentrancy of these routines, you must observe several conventions when allocating and deallo- cating memory. This is most often done when returning data to the user from the window system of a size the caller could not know in advance (for example, a list of fonts or a list of extensions). This occurs because the standard C library routines on many systems are not protected against signals or other multithreaded use. The following analogies to standard I/O library routines have been defined: Xmalloc() Replaces malloc() Xfree() Replaces free() Xcalloc() Replaces calloc() These should be used in place of any calls you would make to the normal C library routines. If you need a single scratch buffer inside a critical sec- tion (for example, to pack and unpack data to and from wire protocol), the general memory allocators may be too expen- sive for use (particularly in output routines, which are performance critical). The routine below returns a scratch buffer for your use: char *_XAllocScratch(display, nbytes) Display *display; unsigned long nbytes; This storage must only be used inside of the critical sec- tion of your stub. Portability Considerations Many machine architectures, including many of the more recent RISC architectures, will not correctly access data at unaligned locations; their compilers will pad out structures to preserve this characteristic. Many other machines capa- ble of unaligned references pad inside of structures as well to preserve alignment, since accessing aligned data is usu- ally much faster. Since the library and the server is using structures to access data at arbitrary points in a byte stream, all data in request and reply packets MUST be natur- ally aligned; that is 16 bit data start on 16 bit boundaries in the request, 32 bit data on 32 bit boundaries. All requests MUST be a multiple of 32 bits in length, to preserve the natural alignment in the data stream. Pad structures out to 32 bit boundaries. Pad information does not have to be zeroed, unless you wish to preserve such fields for future use in your protocol requests. Floating point varies radically between machines, and should be December 18, 1987 - 367 - avoided completely if at all possible. This code may run on machines with 16-bit ``int''s. So, if any integer argument, variable, or return value either can take only non-negative values or is declared as a CARD16 in the protocol, be sure to declare it as ``unsigned int'' and not as ``int''. (This of course does not apply to booleans or enumerations.) Similarly, if any integer argument or return value is declared CARD32 in the protocol, declare it as an ``unsigned long'' and not as ``int'' or ``long''. This also goes for any internal variables that may take on values larger than the maximum 16-bit unsigned int. The library currently assumes that a ``char'' is 8 bits, a ``short'' is 16 bits, an ``int'' is 16 or 32 bits, and a ``long'' is 32 bits. The PackData macro is a half-hearted attempt to deal with the possibility of 32-bit ``shorts''. However, much more work is needed to make this really work properly. Deriving the Correct Extension Opcode The remaining problem a writer of an extension stub routine faces that the core protocol does not face is to map from the call to the proper major and minor opcodes. While there are a number of strategies, the simplest and fastest is out- lined below. 1. Declare an array of pointers, _NFILE long (this is nor- mally found in <stdio.h> and is the number of file descriptors supported on the system, of type XExtCodes. Make sure these are all initialized to NULL. 2. When your stub is entered, your initialization test is just to use the display pointer passed in to access the file descriptor, and an index into the array. If the entry is NULL, then this is the first time you are entering the routine for this display. Call your ini- tialization routine and pass it the display pointer. 3. Once in your initialization routine, call XInitExten- sion, and if it succeeds, store the pointer returned into this array. Make sure to establish a close display handler to allow you to zero the entry. Do whatever other initialization your extension requires. (For example, install event handlers, and so on). Your ini- tialization routine would normally return a pointer to the XExtCodes structure for this extension, which is what would normally be found in your array of pointers. December 18, 1987 - 368 - 4. After returning from your initialization routine, the stub can now continue normally, since it has its major opcode safely in its had in the XExtCodes structure. December 18, 1987 - 369 - Appendix B Version 10 Compatibility Functions Drawing and Filling Polygons and Curves Appendix B - Version 10 Compatibility Functions Xlib pro- vides functions with which you can draw or fill arbitrary polygons or curves. These functions are provided mainly for compatibility with X10 and have no server support. That is, they call other Xlib routines, not the server directly. Thus, if you just have straight lines to draw, using XDraw- Lines or XDrawSegments is much faster. The functions discussed here provide all the functionality of the X10 routines XDraw, XDrawFilled, XDrawPatterned, XDrawDashed, and XDrawTiled. They are as compatible as pos- sible given X11's new line drawing routines. One thing to note, however, is that VertexDrawLastPoint is no longer sup- ported. Also, the error status returned is the opposite of what it was under X10 (this is the X11 standard error status). XAppendVertex and XClearVertexFlag from X10 also are not supported. Just how the graphics context you use is set up actually determines whether you get dashes or not, and so on. Lines are properly joined if they connect and include the closing of a closed figure. (See XDrawLines in X 11 for further details.) The functions discussed here fail (return 0) only if they run out of memory or are passed a Vertex list which has a Vertex with VertexStartClosed set which is not fol- lowed by a Vertex with VertexEndClosed set. To achieve the effects of the V10 XDraw, XDrawDashed, and XDrawPatterned, use XDraw. #include <X11/X10.h> Status XDraw(display, d, gc, vlist, vcount) Display *display; Drawable d; GC gc; Vertex *vlist; int vcount; display Specifies the connection to the X server. December 18, 1987 - 370 - d Specifies the drawable. gc Specifies the graphics context. vlist Specifies a pointer to the list of vertices which indicate what to draw. vcount Specifies how many vertices are in vlist. XDraw draws an arbitrary polygon or curve. The figure drawn is defined by the specified list of Vertexes (vlist). The points are connected by lines as specified in the flags in the vertex structure. Each Vertex, as defined in <X11/Xlib.h>, is a structure with the following elements: typedef struct _Vertex { short x,y; unsigned short flags; } Vertex; The x and y elements are the coordinates of the vertex that are relative to either the upper left inside corner of the drawable (if VertexRelative is 0) or the previous vertex (if VertexRelative is 1). The flags, as defined in X10.h, are as follows: VertexRelative 0x0001 else absolute VertexDontDraw 0x0002 else draw VertexCurved 0x0004 else straight VertexStartClosed 0x0008else not VertexEndClosed 0x0010else not o If VertexRelative is not set, the coordinates are abso- lute (relative to the drawable). The first vertex must be an absolute vertex. o If VertexDontDraw is 1, no line or curve is drawn from the previous vertex to this one. This is analogous to picking up the pen and moving to another place before drawing another line. o If VertexCurved is 1, a spline algorithm is used to draw a smooth curve from the previous vertex, through this one, to the next vertex. Otherwise, a straight line is drawn from the previous vertex to this one. It makes sense to set VertexCurved to 1 only if a previous and next vertex are both defined (either explicitly in the array, or through the definition of a closed curve--see below.) December 18, 1987 - 371 - o It is permissible for VertexDontDraw bits and Vertex- Curved bits to be both be 1. This is useful if you want to define the previous point for the smooth curve, but you do not want an actual curve drawing to start until this point. o If VertexStartClosed is 1, then this point marks the beginning of a closed curve. This vertex must be fol- lowed later in the array by another vertex whose abso- lute coordinates are identical and which has VertexEnd- Closed bit of 1. The points in between from a cycle for the purpose of determining predecessor and succes- sor vertices for the spline algorithm. XDraw uses the following graphics context components: func- tion, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these graphics context mode-dependent components: foreground, background, tile, stipple, ts_s_origin, ts_y_origin, dash_offset, and dash_list. To achieve the effects of the V10 XDrawTiled and XDrawFilled, use XDrawFilled. #include <X11/X10.h> Status XDrawFilled(display, d, gc, vlist, vcount) Display *display; Drawable d; GC gc; Vertex *vlist; int vcount; display Specifies the connection to the X server. d Specifies the drawable. gc Specifies the graphics context. vlist Specifies a pointer to the list of vertices which indicate what to draw. vcount Specifies how many vertices are in vlist. XDrawFilled draws arbitrary polygons or curves and then fills them. XDrawFilled uses the following graphics context components: function, plane_mask, line_width, line_style, cap_style, join_style, fill_style, subwindow_mode, clip_x_origin, clip_y_origin, and clip_mask. This function also uses these December 18, 1987 - 372 - graphics context mode-dependent components: foreground, background, tile, stipple, ts_s_origin, ts_y_origin, dash_offset, dash_list, fill_style and fill_rule. Associating User Data with a Value These functions have been replaced by the context management functions. See Section 10.12 for further information. It is often necessary to associate arbitrary information with resource IDs. Xlib provides the AssocTable functions with which you can make such an association. Application pro- grams often need to be able to easily refer to their own data structures when an event arrives. The XAssocTable sys- tem provides users of the X library with a method of asso- ciating their own data structures with X resources. (Bit- maps, Pixmaps, Fonts, Windows, and so on). An XAssocTable can be used to type X resources. For example, the user may wish to have three or four `types' of windows each with different properties. This can be accomplished by associating each X window ID with a pointer to a `window property' data structure defined by the user. A generic type has been defined in the X library for resource IDs. It is called ``XId''. There are a few guidelines that should be observed when using an XAssocTable: o All X IDs are relative to the specified display. Therefore, if you are using multiple displays you need to be sure the correct display is active before per- forming an XAssocTable operation. XAssocTable imposes no restrictions on the number of X IDs per table, the number of X IDs per display or the number of displays per table. o Because of the hashing scheme used by the asso- ciation mechanism the following rules for determining the size of XAssocTables should be followed. Associa- tions will be made and looked up more efficiently if the table size (number of buckets in the hash- ing system) is a power of two and if there are not more than 8 XIds per bucket. To return a pointer to a newly created assoctable, use XCreateAssocTable. The definition of this function is: XAssocTable *XCreateAssocTable(size) int size; December 18, 1987 - 373 - size Specifies the number of buckets in the hash system of XAssocTable. The "size" argument specifies the number of buckets in the hash system of XAssocTable. For reasons of efficiency the number of buckets should be a power of two. Some size suggestions might be: use 32 buckets per 100 objects; a reasonable maximum number of object per buckets is 8. If there is an error allocating memory for the XAssocT- able, a NULL pointer is returned. To create an entry in a specific assoctable, use XMakeAssoc. The definition of this function is: XMakeAssoc(display, table, x_id, data) Display *display; XAssocTable *table; XID x_id; char *data; display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. data Specifies the data to be associated with the X resource ID. XMakeAssoc inserts data into an XAssocTable keyed on an XId. Data is inserted into the table only once. Redundant inserts are meaningless and cause no problems. The queue in each association bucket is sorted from the lowest XId to the highest XId. To obtain data from a specific assoctable, use XLookUpAssoc. The definition of this function is: char *XLookUpAssoc(display, table, x_id) Display *display; XAssocTable *table; XID x_id; display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. XLookUpAssoc retrieves the data stored in an XAssocTable by December 18, 1987 - 374 - its XId. If an appropriately matching XId can be found in the table the routine will return the data associated with it. If the x_id can not be found in the table the routine will return NULL. To delete an entry from a specific assoctable, use XDeleteAssoc. The definition of this function is: XDeleteAssoc(display, table, x_id) Display *display; XAssocTable *table; XID x_id; display Specifies the connection to the X server. table Specifies the assoc table. x_id Specifies the X resource ID. XDeleteAssoc deletes an association in an XAssocTable keyed on its XId. Redundant deletes (and deletes of non-existent XIds) are meaningless and cause no problems. Deleting asso- ciations in no way impairs the performance of an XAssocT- able. To free the memory associated with a specific assoctable, use XDestroyAssocTable. The definition of this function is: XDestroyAssocTable(table) XAssocTable *table; table Specifies the assoc table. Using an XAssocTable after it has been destroyed is guaranteed to have unpredictable and probably disastrous consequences! December 18, 1987 - 375 - Appendix C X Font Cursors Appendix C - X Font Cursors The following are the available cursors and their shapes in fonts. #define XC_num_glyphs 154 #define XC_X_cursor 0 #define XC_arrow 2 #define XC_based_arrow_down 4 #define XC_based_arrow_up 6 #define XC_boat 8 #define XC_bogosity 10 #define XC_bottom_left_corner 12 #define XC_bottom_right_corner 14 #define XC_bottom_side 16 #define XC_bottom_tee 18 #define XC_box_sprial 20 #define XC_center_ptr 22 #define XC_circle 24 #define XC_clock 26 #define XC_coffee_mug 28 #define XC_cross 30 #define XC_cross_reverse 32 #define XC_crosshair 34 #define XC_diamond_cross 36 #define XC_dot 38 #define XC_dot_box_mask 40 #define XC_double_arrow 42 #define XC_draft_large 44 #define XC_draft_small 46 #define XC_draped_box 48 #define XC_exchange 50 #define XC_fleur 52 #define XC_gobbler 54 #define XC_gumby 56 #define XC_hand 58 #define XC_hand1_mask 60 #define XC_heart 62 #define XC_icon 64 #define XC_iron_cross 66 #define XC_left_ptr 68 #define XC_left_side 70 #define XC_left_tee 72 #define XC_leftbutton 74 #define XC_ll_angle 76 #define XC_lr_angle 78 #define XC_man 80 #define XC_middlebutton 82 December 18, 1987 - 376 - #define XC_mouse 84 #define XC_pencil 86 #define XC_pirate 88 #define XC_plus 90 #define XC_question_arrow 92 #define XC_right_ptr 94 #define XC_right_side 96 #define XC_right_tee 98 #define XC_rightbutton 100 #define XC_rtl_logo 102 #define XC_sailboat 104 #define XC_sb_down_arrow 106 #define XC_sb_h_double_arrow 108 #define XC_sb_left_arrow 110 #define XC_sb_right_arrow 112 #define XC_sb_up_arrow 114 #define XC_sb_v_double_arrow 116 #define XC_shuttle 118 #define XC_sizing 120 #define XC_spider 122 #define XC_spraycan 124 #define XC_star 126 #define XC_target 128 #define XC_tcross 130 #define XC_top_left_arrow 132 #define XC_top_left_corner 134 #define XC_top_right_corner 136 #define XC_top_side 138 #define XC_top_tee 140 #define XC_trek 142 #define XC_ul_angle 144 #define XC_umbrella 146 #define XC_ur_angle 148 #define XC_watch 150 #define XC_xterm 152 December 18, 1987 - 377 - Appendix D Xlib Functions and Protocol Requests Appendix D - Xlib Functions and Protocol Requests The fol- lowing tables provide a information about Xlib and the X protocol. The first table lists each Xlib function (in alphabetical order) and the corresponding protocol request that it generates. The second table lists each X protocol request (in alphabetical order) and the Xlib functions that reference it. ______________________________________________________ Xlib Function Protocol Request ______________________________________________________ XActivateScreenSaver ForceScreenSaver XAddHost ChangeHosts XAddHosts ChangeHosts XAddToSaveSet ChangeSaveSet XAllocColor AllocColor XAllocColorCells AllocColorCells XAllocColorPlanes AllocColorPlanes XAllocNamedColor AllocNamedColor XAllowEvents AllowEvents XAutoRepeatOff ChangeKeyboardControl XAutoRepeatOn ChangeKeyboardControl XBell Bell XChangeActivePointerGrab ChangeActivePointerGrab XChangeGC ChangeGC XChangeKeyboardControl ChangeKeyboardControl XChangeKeyboardMapping ChangeKeyboardMapping XChangePointerControl ChangePointerControl XChangeProperty ChangeProperty XChangeSaveSet ChangeSaveSet XChangeWindowAttributes ChangeWindowAttributes XCirculateSubwindows CirculateWindow XCirculateSubwindowsDown CirculateWindow XCirculateSubwindowsUp CirculateWindow XClearArea ClearArea XClearIconWindow GetProperty XClearWindow ClearArea XConfigureWindow ConfigureWindow XConvertSelection ConvertSelection XCopyArea CopyArea XCopyColormapAndFree CopyColormapAndFree XCopyGC CopyGC XCopyPlane CopyPlane XCreateColormap CreateColormap XCreateFontCursor CreateGlphyCursor December 18, 1987 - 378 - ______________________________________________________ Xlib Function Protocol Request ______________________________________________________ XCreateGC CreateGC XCreateGlyphCursor CreateGlyphCursor XCreatePixmap CreatePixmap XCreatePixmapCursor CreateCursor XCreateSimpleWindow CreateWindow XCreateWindow CreateWindow XDefineCursor ChangeWindowAttributes XDeleteProperty DeleteProperty XDestroySubwindows DestroySubwindows XDestroyWindow DestroyWindow XDisableAccessControl SetAccessControl XDrawArc PolyArc XDrawArcs PolyArc XDrawImageString ImageText8 XDrawImageString16 ImageText16 XDrawLine PolySegment XDrawLines PolyLine XDrawPoint PolyPoint XDrawPoints PolyPoint XDrawRectangle PolyRectangle XDrawRectangles PolyRectangle XDrawSegments PolySegment XDrawString PolyText8 XDrawString16 PolyText16 XDrawText PolyText8 XDrawText16 PolyText16 XEnableAccessControl SetAccessControl XFetchBytes GetProperty XFetchName GetProperty XFillArc PolyFillArc XFillArcs PolyFillArc XFillPolygon FillPoly XFillRectangle PolyFillRectangle XFillRectangles PolyFillRectangle XForceScreenSaver ForceScreenSaver XFreeColormap FreeColormap XFreeColors FreeColors XFreeCursor FreeCursor XFreeFont CloseFont XFreeGC FreeGC XFreePixmap FreePixmap XGetAtomName GetAtomName XGetFontPath GetFontPath XGetGeometry GetGeometry XGetIconSizes GetProperty XGetIconWindow GetProperty XGetImage GetImage XGetInputFocus GetInputFocus XGetKeyboardContol GetKeyboardControl XGetKeyboardMapping GetKeyboardMapping XGetMotionEvents GetMotionEvents December 18, 1987 - 379 - ______________________________________________________ Xlib Function Protocol Request ______________________________________________________ XGetNormalHints GetProperty XGetPointerContol GetPointerControl XGetPonterMapping GetPointerMapping XGetScreenSaver SetScreenSaver XGetSelectionOwner GetSelectionOwner XGetSizeHints GetProperty XGetWMHints GetProperty XGetWindowAttributes GetWindowAttributes XGetWindowAttributes GetGeometry XGetWindowProperty GetProperty XGetZoomHints GetProperty XGrabButton GrabButton XGrabKey GrabKey XGrabKeyboard GrabKeyboard XGrabPointer GrabPointer XGrabServer GrabServer XInitExtension QueryExtension XInstallColormap InstallColormap XInternAtom InternAtom XKillClient KillClient XListExtensions ListExtensions XListFonts ListFonts XListFontsWithInfo ListFontsWithInfo XListHosts ListHosts XListInstalledColormaps ListInstalledColormaps XListProperties ListProperties XLoadFont OpenFont XLoadQueryFont OpenFont QueryFont XLookupColor LookupColor XLowerWindow ConfigureWindow XMapRaised ConfigureWindow MapWindow XMapSubwindows MapSubwindows XMapWindow MapWindow XMoveResizeWindow ConfigureWindow XMoveWindow ConfigureWindow XNoOp NoOperation XOpenDisplay CreateGC XParseColor LookupColor XPutImage PutImage XQueryBestCursor QueryBestSize XQueryBestSize QueryBestSize XQueryBestStipple QueryBestSize XQueryBestTile QueryBestSize XQueryColor QueryColors XQueryColors QueryColors XQueryExtension QueryExtension XQueryKeymap QueryKeymap XQueryPointer QueryPointer XQueryTextExtents QueryTextExtents December 18, 1987 - 380 - ______________________________________________________ Xlib Function Protocol Request ______________________________________________________ XQueryTextExtents16 QueryTextExtents XQueryTree QueryTree XRaiseWindow ConfigureWindow XRecolorCursor RecolorCursor XRemoveFromSaveSet ChangeSaveSet XRemoveHost ChangeHosts XRemoveHosts ChangeHosts XReparentWindow ReparentWindow XResetScreenSaver ForceScreenSaver XResizeWindow ConfigureWindow XRestackWindows ConfigureWindow XRotateBuffers RotateProperties XRotateWindowProperties RotateProperties XSelectInput ChangeWindowAttributes XSendEvent SendEvent XSetAccessControl SetAccessControl XSetArcMode ChangeGC XSetBackground ChangeGC XSetClipMask ChangeGC XSetClipOrigin ChangeGC XSetClipRectangles SetClipRectangles XSetCloseDownMode SetCloseDownMode XSetCommand ChangeProperty XSetDashes SetDashes XSetFillRule ChangeGC XSetFillStyle ChangeGC XSetFont ChangeGC XSetFontPath SetFontPath XSetForeground ChangeGC XSetFunction ChangeGC XSetGraphicsExposures ChangeGC XSetIconSizes ChangeProperty XSetIconWindow ChangeProperty XSetInputFocus SetInputFocus XSetLineAttributes ChangeGC XSetModifierMapping SetModifierMapping XSetNormalHints ChangeProperty XSetPlaneMask ChangeGC XSetPointerMapping SetPointerMapping XSetResizeHint ChangeProperty XSetScreenSaver SetScreenSaver XSetSelectionOwner SetSelectionOwner XSetSizeHints ChangeProperty XSetStandardProperties ChangeProperty XSetState ChangeGC XSetStipple ChangeGC XSetSubwindowMode ChangeGC XSetTile ChangeGC XSetTSOrigin ChangeGC XSetWMHints ChangeProperty XSetWindowBackground ChangeWindowAttributes December 18, 1987 - 381 - ______________________________________________________ Xlib Function Protocol Request ______________________________________________________ XSetWindowBackgroundPixmap ChangeWindowAttributes XSetWindowBorder ChangeWindowAttributes XSetWindowBorderPixmap ChangeWindowAttributes XSetWindowBorderWidth ConfigureWindow XSetWindowColormap ChangeWindowAttributes XSetZoomHints ChangeProperty XStoreBuffer ChangeProperty XStoreBytes ChangeProperty XStoreColor StoreColors XStoreColors StoreColors XStoreName ChangeProperty XStoreNamedColor StoreNamedColor XSync GetInputFocus XTranslateCoordinates TranslateCoordinates XUndefineCursor ChangeWindowAttributes XUngrabButton UngrabButton XUngrabKey UngrabKey XUngrabKeyboard UngrabKeyboard XUngrabPointer UngrabPointer XUngrabServer UngrabServer XUninstallColormap UninstallColormap XUnloadFont CloseFont XUnmapSubwindows UnmapSubwindows XUnmapWindow UnmapWindow XWarpPointer WarpPointer December 18, 1987 - 382 - ______________________________________________________ Protocol Request Xlib Function ______________________________________________________ AllocColor XAllocColor AllocColorCells XAllocColorCells AllocColorPlanes XAllocColorPlanes AllocNamedColor XAllocNamedColor AllowEvents XAllowEvents Bell XBell SetAccessControl XDisableAccessControl XEnableAccessControl XSetAccessControl ChangeActivePointerGrab XChangeActivePointerGrab SetCloseDownMode XSetCloseDownMode ChangeGC XChangeGC XSetArcMode XSetBackground XSetClipMask XSetClipOrigin XSetFillRule XSetFillStyle XSetFont XSetForeground XSetFunction XSetGraphicsExposures XSetLineAttributes XSetPlaneMask XSetState XSetStipple XSetSubwindowMode XSetTile XSetTSOrigin ChangeHosts XAddHost XAddHosts XRemoveHost XRemoveHosts ChangeKeyboardControl XAutoRepeatOff XAutoRepeatOn XChangeKeyboardControl ChangeKeyboardMapping XChangeKeyboardMapping ChangePointerControl XChangePointerControl ChangeProperty XChangeProperty XSetCommand XSetIconSizes XSetIconWindow XSetNormalHints XSetResizeHint XSetSizeHints XSetStandardProperties XSetWMHints XSetZoomHints XStoreBuffer XStoreBytes XStoreName December 18, 1987 - 383 - ______________________________________________________ Protocol Request Xlib Function ______________________________________________________ ChangeSaveSet XAddToSaveSet XChangeSaveSet XRemoveFromSaveSet ChangeWindowAttributes XChangeWindowAttributes XDefineCursor XSelectInput XSetWindowBackground XSetWindowBackgroundPixmap XSetWindowBorder XSetWindowBorderPixmap XSetWindowColormap XUndefineCursor CirculateWindow XCirculateSubwindowsDown XCirculateSubwindowsUp XCirculateSubwindows ClearArea XClearArea XClearWindow CloseFont XFreeFont XUnloadFont ConfigureWindow XConfigureWindow XLowerWindow XMapRaised XMoveResizeWindow XMoveWindow XRaiseWindow XResizeWindow XRestackWindows XSetWindowBorderWidth ConvertSelection XConvertSelection CopyArea XCopyArea CopyColormapAndFree XCopyColormapAndFree CopyGC XCopyGC CopyPlane XCopyPlane CreateColormap XCreateColormap CreateCursor XCreatePixmapCursor CreateGC XCreateGC XOpenDisplay CreateGlphyCursor XCreateFontCursor XCreateGlyphCursor CreatePixmap XCreatePixmap CreateWindow XCreateSimpleWindow XCreateWindow DeleteProperty XDeleteProperty DestroySubwindows XDestroySubwindows DestroyWindow XDestroyWindow FillPoly XFillPolygon ForceScreenSaver XActivateScreenSaver XForceScreenSaver XResetScreenSaver FreeColormap XFreeColormap FreeColors XFreeColors December 18, 1987 - 384 - ______________________________________________________ Protocol Request Xlib Function ______________________________________________________ FreeCursor XFreeCursor FreeGC XFreeGC FreePixmap XFreePixmap GetAtomName XGetAtomName GetFontPath XGetFontPath GetGeometry XGetGeometry XGetWindowAttributes GetImage XGetImage GetInputFocus XGetInputFocus XSync GetKeyboardControl XGetKeyboardContol GetKeyboardMapping XGetKeyboardMapping GetMotionEvents XGetMotionEvents GetPointerControl XGetPointerContol GetPointerMapping XGetPonterMapping GetProperty XClearIconWindow XFetchBytes XFetchName XGetIconSizes XGetIconWindow XGetNormalHints XGetSizeHints XGetWMHints XGetWindowProperty XGetZoomHints GetSelectionOwner XGetSelectionOwner GetWindowAttributes XGetWindowAttributes GrabButton XGrabButton GrabKey XGrabKey GrabKeyboard XGrabKeyboard GrabPointer XGrabPointer GrabServer XGrabServer ImageText16 XDrawImageString16 ImageText8 XDrawImageString InstallColormap XInstallColormap InternAtom XInternAtom KillClient XKillClient ListExtensions XListExtensions ListFonts XListFonts ListFontsWithInfo XListFontsWithInfo ListHosts XListHosts ListInstalledColormaps XListInstalledColormaps ListProperties XListProperties LookupColor XLookupColor XParseColor MapSubwindows XMapSubwindows MapWindow XMapRaised XMapWindow NoOperation XNoOp OpenFont XLoadFont XLoadQueryFont December 18, 1987 - 385 - ______________________________________________________ Protocol Request Xlib Function ______________________________________________________ PolyArc XDrawArc XDrawArcs PolyFillArc XFillArc XFillArcs PolyFillRectangle XFillRectangle XFillRectangles PolyLine XDrawLines PolyPoint XDrawPoint XDrawPoints PolyRectangle XDrawRectangle XDrawRectangles PolySegment XDrawLine XDrawSegments PolyText16 XDrawString16 XDrawText16 PolyText8 XDrawString XDrawText PutImage XPutImage QueryBestSize XQueryBestCursor XQueryBestSize XQueryBestStipple XQueryBestTile QueryColors XQueryColor XQueryColors QueryExtension XInitExtension XQueryExtension QueryFont XLoadQueryFont QueryKeymap XQueryKeymap QueryPointer XQueryPointer QueryTextExtents XQueryTextExtents XQueryTextExtents16 QueryTree XQueryTree RecolorCursor XRecolorCursor ReparentWindow XReparentWindow RotateProperties XRotateBuffers XRotateWindowProperties SendEvent XSendEvent SetClipRectangles XSetClipRectangles SetCloseDownMode XSetCloseDownMode SetDashes XSetDashes SetFontPath XSetFontPath SetInputFocus XSetInputFocus SetModifierMapping XSetModifierMapping SetPointerMapping XSetPointerMapping SetScreenSaver XGetScreenSaver XSetScreenSaver SetSelectionOwner XSetSelectionOwner StoreColors XStoreColor XStoreColors StoreNamedColor XStoreNamedColor TranslateCoordinates XTranslateCoordinates December 18, 1987 - 386 - ______________________________________________________ Protocol Request Xlib Function ______________________________________________________ UngrabButton XUngrabButton UngrabKey XUngrabKey UngrabKeyboard XUngrabKeyboard UngrabPointer XUngrabPointer UngrabServer XUngrabServer UninstallColormap XUninstallColormap UnmapSubwindows XUnmapSubWindows UnmapWindow XUnmapWindow WarpPointer XWarpPointer December 18, 1987 - 387 - Glossary Glossary access control list X maintains a list of hosts from which client programs may be run. By default, only programs on the local host may use the display, plus any hosts specified in an initial list read by the server. This ``access control list'' can be changed by clients on the local host. Some server implementations may also implement other authorization mechanisms in addition to or in place of this mechanism. The action of this mechanism may be conditional based on the authorization protocol name and data received by the server at connection setup. active grab A grab is "active" when the pointer or keyboard is actually owned by the single grabbing client. ancestor If W is an inferior of A, then A is an ``ancestor'' of W. atom An ``atom'' is a unique ID corresponding to a string name. Atoms are used to identify properties, types, and selections. background Windows may have a ``background''. If a window has a background, it can either be a solid background or a tile pattern, and it will be repainted automatically by the server. backing store When a server maintains the contents of a window, the off-screen saved pixels are known as a ``backing store''. bit gravity When a window is resized, the contents of the window are not necessarily discarded. It is possible to request the server (though no guarantees are made) to relocate the previous contents to some region of the December 18, 1987 - 388 - window. This attraction of window contents for some location of a window is known as ``bit gravity''. bit plane On a color display, each pixel has more than one bit defined. Data in display memory can be thought of either as pixels (multiple bits per pixel) or as bit planes (one bit plane for each usable bit in the pixel). bitmap A ``bitmap'' is a pixmap of depth one. border Windows can have borders that are zero (0) or more pix- els wide. If a window has a border, the border can be a solid color or a tile pattern, and it will be repainted automatically by the server. button grabbing Buttons on the pointer may be passively ``grabbed'' by a client. When the button is pressed, the pointer is then actively grabbed by the client. byte order For image (pixmap/bitmap) data, byte order is defined by the server, and clients with different native byte ordering must swap bytes as necessary. For all other parts of the protocol, the byte order is defined by the client, and the server swaps bytes as necessary. children The ``children'' of a window are its first-level subwindows. class Windows can be of different types. See the entries for `` InputOnly '.PN "InputOutput" windows'' for further information about valid window types. client An application program connects to the window system server by some interprocess communication (IPC) path, such as a TCP connection or a shared memory buffer. This program is referred to as a ``client'' of the win- dow system server. More precisely, the client is the December 18, 1987 - 389 - IPC path itself. A program with multiple paths open to the server is viewed as multiple clients by the proto- col. Resource lifetimes are controlled by connection lifetimes, not by program lifetimes. clipping region In a graphics context, a bitmap or list of rectangles can be specified to restrict output to a particular region of the window. The image defined by the bitmap or rectangles is called a ``clipping region''. color map A ``color map'' consists of a set of entries defining color values. The color map associated with a window is used to display the contents of the window; each pixel value indexes the color map to produce RGB values that drive the guns of a monitor. Depending on hardware limitations, one or more color maps may be installed at one time, such that windows associated with those maps display with true colors. connection The IPC path between the server and client program is known as a ``connection''. A client program typically (but not necessarily) has one connection to the server over which requests and events are sent. containment A window ``contains'' the pointer if the window is viewable and the hotspot of the cursor is within a visible region of the window or a visible region of one of its inferiors. The border of the window is included as part of the window for containment. The pointer is ``in'' a window if the window contains the pointer but no inferior contains the pointer. coordinate system The coordinate system has X horizontal and Y vertical, with the origin [0, 0] at the upper left. Coordinates are discrete, and in terms of pixels. Each window and pixmap has its own coordinate system. For a window, the origin is at the inside upper left, inside the border. cursor A ``cursor'' is the visible shape of the pointer on a screen. It consists of a hot spot, a source bitmap, a shape bitmap, and a pair of colors. The cursor defined for a window controls the visible appearance when the December 18, 1987 - 390 - pointer is in that window. depth The ``depth'' of a window or pixmap is the number of bits per pixel it has. The depth of a graphics context is the depth of the drawables it can be used in con- junction with for graphics output. device Keyboards, mice, tablets, track-balls, button boxes, etc. are all collectively known as input ``devices''. Pointers can have one or more buttons (usually, the most common number is three). The core protocol only deals with two devices: ``the keyboard'' and ``the pointer''. direct color A class of color map in which a pixel value is decom- posed into three separate subfields for indexing. One subfield indexes an array to produce red intensity values; the second subfield indexes a second array to produce blue intensity values; and the third subfield indexes a third array to produce green intensity values. The RGB (red, green, and blue) values in the colormap entry can be changed dynamically. display A ``display'' is a set of one or more screens that are driven by a single X server. The Xlib Display struc- ture contains all information about the particular display and its screens as well as the state that Xlib needs to communicate with the display over a particular connection. drawable Both windows and pixmaps may be used as sources and destinations in graphics operations. These are collec- tively known as ``drawables''. However, an InputOnly window cannot be used as a source or destination in a graphics operation. event Clients are informed of information asynchronously via ``events''. These events may be either asynchronously generated from devices, or generated as side effects of client requests. Events are grouped into types. Events are never sent to a client by the server unless the client has specifically asked to be informed of that December 18, 1987 - 391 - type of event, but clients ndow described can force events to be sent to other clients. Events are typi- cally reported relative to a window. event mask Events are requested relative to a window. The set of event types a client requests relative to a window is described by using an ``event mask''. event sychronization There are certain race conditions possible when demul- tiplexing device events to clients (in particular deciding where pointer and keyboard events should be sent when in the middle of window management opera- tions). The event synchronization mechanism allows syn- chronous processing of device events. event propagation Device-related events ``propagate'' from the source window to ancestor windows until some client has expressed interest in handling that type of event, or until the event is discarded explicitly. event source The smallest window containing the pointer is the ``source'' of a device related event. exposure event Servers do not guarantee to preserve the contents of windows when windows are obscured or reconfigured. ``Exposure'' events are sent to clients to inform them when contents of regions of windows have been lost. extension Named ``extensions'' to the core protocol can be defined to extend the system. Extension to output requests, resources, and event types are all possible, and expected. font A ``font'' is an array of glyphs (typically charac- ters). The protocol does no translation or interpreta- tion of character sets. The client simply indicates values used to index the glyph array. A font contains additional metric information to determine inter-glyph and inter-line spacing. December 18, 1987 - 392 - frozen events Clients can ``freeze'' event processing while they change the screen. GC Shorthand for ``graphics context''. An equivalent shorthand is gcontext. See graphic context. glyph A ``glyph'' is an image, typically of a character, in a font. grab Keyboard keys, the keyboard, pointer buttons, the pointer, and the server can be ``grabbed'' for exclusive use by a client. In general, these facilities are not intended to be used by normal applications, but are intended for various input and window managers to implement various styles of user interfaces. graphic context Various information for graphics output is stored in a ``graphics context'' (``GC'' or ``gcontext''), such as foreground pixel, background pixel, line width, clip- ping region, etc. A graphics context can only be used with drawables that have the same root and the same depth as the graphics context. gravity The contents of windows, or subwindows themselves, have a ``gravity''. This determines how they will be moved when a window ID resized. See ``bit gravity'' and ``window gravity''. gray scale Gray scale can be viewed as a degenerate case of pseudo color, in which case the red, green, and blue values in any given color map entry are equal, thus producing shades of gray. The gray values can be changed dynami- cally. hotspot A cursor has an associated ``hot spot'' which defines a point in the cursor that corresponds to the coordinates reported for the pointer. identifier December 18, 1987 - 393 - Each resource has an ``identifier'', a unique value associated with it that clients use to name the resource. An identifier can be used over any connection to name the resource. inferiors The ``inferiors'' of a window are all of the subwindows nested below it: the children, the children's chil- dren, etc. input focus The ``input focus'' is where keyboard input goes. Key- board events are by default sent to the client express- ing interest on the window the pointer is in. This is said to be a ``real estate driven'' input focus. It is also possible to attach the keyboard input to a specific window. Events will then be sent to the appropriate client independent of the pointer position. input manager Control over keyboard input is typically provided by an ``input manager'' client, usually part of a window manager. InputOnly window A window that cannot be used for graphics requests. InputOnly windows are ``invisible'' and can be used to control such things as cursors, input event generation, and grabbing. InputOnly windows cannot have InputOut- put windows as inferiors. InputOutput window The ``normal'' kind of window that is used for both input and output. It usually has a background. Inpu- tOutput windows can have both InputOutput and InputOnly windows as inferiors. key grabbing Keys on the keyboard may be passively ``grabbed'' by a client. When the key is pressed, the keyboard is then actively grabbed by the client. keyboard grabbing A client can actively ``grab'' control of the keyboard, and key events will be sent to that client rather than the client the events would normally have been sent to. December 18, 1987 - 394 - keysym An encoding of a symbol on a keycap on a keyboard. mapped A window is said to be ``mapped'' if a map call has been performed on it. Unmapped windows and their infe- riors are never viewable or visible. modifier keys Shift, Control, Meta, Super, Hyper, ALT, Compose, Apple, CapsLock, ShiftLock, and similar keys are called ``modifier'' keys. monochrome A special case of static gray, in which there are only two color map entries. obscure A window is ``obscured'' if some other window ``obscures'' it. A window can be partially obscured and still have visible regions. obscures Window A ``obscures'' window B if both are viewable InputOutput windows, if A is higher in the global stacking order, and if the rectangle defined by the outside edges of A intersects the rectangle defined by the outside edges of B. Note the (fine) distinction with ``occludes''. Also note that window borders are included in the calculation. occlude A window is ``occluded'' if some other window ``occludes'' it. occludes Window A ``occludes'' window B if both are mapped, if A is higher in the global stacking order, and if the rec- tangle defined by the outside edges of A intersects the rectangle defined by the outside edges of B. Note the (fine) distinction with "obscures". Also note that window borders are included in the calculation. Note that InputOnly windows never obscure other windows but can occludes other windows. padding December 18, 1987 - 395 - Some padding bytes are inserted in the data stream to maintain alignment of the protocol requests on natural boundaries. This increases ease of portability to some machine architectures. parent window If C is a child of P, then P is the ``parent'' of C. passive grab Grabbing a key or button is a ``passive'' grab. The grab activates when the key or button is actually pressed. pixel value A ``pixel'' is an N-bit value (at a single point), where N is the number of bit planes (that is, the depth of) used in a particular window or pixmap. A pixel in a window indexes a color map to derive an actual color to be displayed. pixmap A ``pixmap'' is a three dimensional array of bits. A pixmap is normally thought of as a two dimensional array of pixels, where each pixel can be a value from 0 to (2^N)-1, where N is the depth (z axis) of the pix- map. A pixmap can also be thought of as a stack of N bitmaps. A pixmap can only be used on the screen that it was created in. plane When a pixmap or window is thought of as a stack of bitmaps, each bitmap is called a ``plane'' or ``bit plane''. plane mask Graphics operations can be restricted to only affect a subset of bit planes of a destination. A ``plane mask'' is a bit mask describing which planes are to be modi- fied, and is stored in a graphics context. pointer The ``pointer'' is the pointing device currently attached to the cursor, and tracked on the screens. pointer grabbing December 18, 1987 - 396 - A client can actively ``grab'' control of the pointer, and button and motion events will be sent to that client rather than the client the events would normally have been sent to. pointing device A ``pointing device'' is typically a mouse or tablet, or some other device with effective dimensional motion. Only one visible cursor is defined by the core proto- col, and it tracks whatever pointing device is attached as the pointer. property Windows may have associated ``properties'', consisting of a name, a type, a data format, and some data. The protocol places no interpretation on properties. They are intended as a general-purpose naming mechanism for clients. For example, clients might share information such as resize hints, program names, and icon formats with a window manager via properties. property list The ``property list'' of a window is the list of pro- perties that have been defined for the window. pseudo color A class of color map in which a pixel value indexes the color map entry to produce independent red, green, and blue values. That is, the color map is viewed as an array of triples (RGB values). The RGB values can be changed dynamically. raise Changing the stacking order of a window so as to occlude another window is to ``raise'' that window. rectangle A ``rectangle'' specified by [x,y,w,h] has an (infin- itely thin) outline path with corners at [x,y], [x+w,y], [x+w,y+h] and [x, y+h]. When a rectangle is filled, the lower right edges are not drawn. For exam- ple, if w=h=0, nothing would be drawn. For w=h=1, a single pixel would be drawn. redirect control December 18, 1987 - 397 - Window managers (or client programs) may wish to enforce window layout policy in various ways. When a client attempts to change the size or position of a window, the operation may be ``redirected'' to a speci- fied client, rather than the operation actually being performed. reply Information requested by a client program by means of the X protocol is sent back to the client with a ``reply.'' Both events and replys are multipexed on the same connection. Most requests do not generate replies. Some requests generate multiple replies. request A command to the server is called a ``request''. It is a single block of data sent over a connection. resource Windows, pixmaps, cursors, fonts, graphics contexts, and color maps are known as ``resources''. They all have unique identifiers associated with them for naming purposes. The lifetime of a resource is bounded by the lifetime of the connection over which the resource was created. RGB values ``Red, green, and blue'' intensity values are used to define a color. These values are always represented as 16 bit unsigned numbers, with zero the minimum inten- sity and 65535 the maximum intensity. The X server scales these values to match the display hardware. root The ``root'' of a pixmap or gcontext is the same as the root of whatever drawable was used when the pixmap or gcontext was created. The ``root'' of a window is the root window under which the window was created. root window Each screen has a ``root window'' covering it. It can- not be reconfigured or unmapped, but otherwise acts as a full fledged window. A root window has no parent. save set December 18, 1987 - 398 - The ``save set'' of a client is a list of other client's windows which, if they are inferiors of one of the client's windows at connection close, should not be destroyed, and which should be remapped if it is unmapped. Save sets are typically used by window managers to avoid lost windows if the manager should terminate abnormally. scanline A ``scanline'' is a list of pixel or bit values viewed as a horizontal row (all values having the same y coor- dinate) of an image, with the values ordered by increasing x coordinate. scanline order An image represented in ``scanline order'' contains scanlines ordered by increasing y coordinate. screen A server may provide several independent ``screens'', which typically have physically independent monitors. This would be the expected configuration when there is only a single keyboard and pointer shared among the screens. A Screen structure contains the information about that screen and is linked to the Dislay struc- ture. selection A ``selection'' can be thought of as an indirect pro- perty with dynamic type. That is, rather than having the property stored in the X server, it is maintained by some client (the "owner"). A selection is global in nature, being thought of as belonging to the user (but maintained by clients), rather than being private to a particular window subhierarchy or a particular set of clients. When a client asks for the contents of a selection, it specifies a selection ``target type''. This target type can be used to control the transmitted representation of the contents. For example, if the selection is ``the last thing the user clicked on'', and that is currently an image, then the target type might specify whether the contents of the image should be sent in XYFormat or ZFormat. The target type can also be used to control the class of contents transmitted, for example, asking for the ``looks'' (fonts, line spacing, indentation, and so forth) of a paragraph selection, rather than the text of the paragraph. The target type can also be used for other purposes. The semantics are not constrained by December 18, 1987 - 399 - the protocol. server The ``server'', also referred to as the``X server'', provides the basic windowing mechanism. It handles IPC connections from clients, demultipexes graphics requests onto the screens, and multiplexes input back to the appropriate clients. server grabbing The server can be ``grabbed'' by a single client for exclusive use. This prevents processing of any requests from other client connections until the grab is com- plete. This is typically only a transient state for such things as rubber-banding and pop-up menus, or to execute requests indivisibly. sibling Children of the same parent window are known as ``sibling'' windows. stacking order Sibling windows may ``stack'' on top of each other. Windows above both obscure and occlude lower windows. This is similar to paper on a desk. The relationship between sibling windows is known as the ``stacking order''. static color Static color can be viewed as a degenerate case of pseudo color, in which the RGB values are predefined and read-only. See pseudo color. static gray Static gray can be viewed as a degenerate case of gray scale, in which the gray values are predefined and read-only. The values are typically (near-)linear increasing ramps. See gray scale. stipple A ``stipple pattern'' is a bitmap that is used to tile a region to serve as an additional clip mask for a fill operation with the foreground color. status December 18, 1987 - 400 - Many Xlib functions return a success status. If the function does not succeed, however, its arguments ar not disturbed. tile A pixmap can be replicated in two dimensions to ``tile'' a region. The pixmap itself is also known as a ``tile''. timestamped A time value, expressed in milliseconds, typically since the last server reset. Timestamp values wrap around (after about 49.7 days). The server, given its current time is represented by timestamp T, always interprets timestamps from clients by treating half of the timestamp space as being earlier in time than T, and half of the timestamp space as being later in time than T. One timestamp value, represented by the con- stant CurrentTime is never generated by the server. This value is reserved for use in requests to represent the current server time. true color True color can be viewed as a degenerate case of direct color, in which the subfields in the pixel value directly encode the corresponding RGB values. That is, the color map has predefined read-only RGB values. The values are typically (near-)linear increasing ramps. See direct color. type A type is an arbitrary atom used to identify the interpretation of property data. Types are completely uninterpreted by the server. They are solely for the benefit of clients. X predefines type atoms for many frequently used types, and clients also can define new types. viewable A window is ``viewable'' if it and all of its ancestors are mapped. This does not imply that any portion of the window is actually visible. Graphics requests can be performed on a window when it is not viewable, but out- put will not be retained unless the server is maintain- ing backing store. visible December 18, 1987 - 401 - A region of a window is ``visible'' if someone looking at the screen can actually ``see'' it: the window is viewable and the region is not occluded by any other window. window gravity When windows are resized, subwindows may be reposi- tioned automatically relative to some position in the window. This attraction of a subwindow to some part of its parent is known as ``window gravity''. window manager Manipulation of windows on the screen, and much of the user interface (policy) is typically provided by a ``window manager'' client. XYFormat The data for a pixmap is said to be in ``XYFormat'' if it is organized as a set of bitmaps representing indi- vidual bit planes. ZFormat The data for a pixmap is said to be in ``ZFormat'' if it is organized as a set of pixel values in scanline order.